From 93d945e675624fa8786fc0fd13ff6c6f6074cd13 Mon Sep 17 00:00:00 2001 From: Tamal Saha Date: Fri, 12 Jun 2026 20:59:13 +0600 Subject: [PATCH 1/7] Add ArgoCD and OpenShift install guides for KubeStash Document deploying KubeStash declaratively via ArgoCD using the ace-user-roles, license-proxyserver and kubestash Application manifests, and document two ways to install on OpenShift: the standard chart with global.distro.openshift/ubi values, and the Red Hat certified chart paired with the separate CRDs chart. Signed-off-by: Tamal Saha --- docs/setup/install/kubestash/index.md | 229 ++++++++++++++++++++++++++ 1 file changed, 229 insertions(+) diff --git a/docs/setup/install/kubestash/index.md b/docs/setup/install/kubestash/index.md index 23d5acc..2ad13db 100644 --- a/docs/setup/install/kubestash/index.md +++ b/docs/setup/install/kubestash/index.md @@ -114,6 +114,235 @@ As you can see from the above output that KubeStash has created `Addon` objects. Now, you are ready to [take your first backup](/docs/guides/README.md) using KubeStash. +## Install using ArgoCD + +You can deploy KubeStash declaratively using [ArgoCD](https://argo-cd.readthedocs.io/). The setup is composed of three `Application` manifests that should be applied in the following order: + +1. `ace-user-roles` — installs the ClusterRoles used by KubeStash (and other AppsCode products) so that user impersonation works correctly. +2. `license-proxyserver` — installs the AppsCode License Proxyserver, which obtains and rotates the KubeStash license from the AppsCode platform automatically. You no longer need to download a license file when this is used. +3. `kubestash` — installs the KubeStash operator itself. + +### Prerequisites + +- An ArgoCD installation reachable at the `argocd` namespace. +- An AppsCode platform token. You can obtain one from the [AppsCode platform](https://appscode.com/). Replace the placeholder value in the `license-proxyserver` manifest with your token. + +### 1. Install ace-user-roles + +Save the following manifest as `ace-user-roles.yaml` and apply it with `kubectl apply -f ace-user-roles.yaml`: + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: ace-user-roles + namespace: argocd +spec: + destination: + namespace: kubeops + server: https://kubernetes.default.svc + project: default + source: + chart: ace-user-roles + helm: + values: | + enableClusterRoles: + ace: false + appcatalog: true + catalog: false + cert-manager: false + kubedb: true + kubedb-ui: false + kubestash: true # enable if used + kubevault: true # enable if used + license-proxyserver: true + metrics: true + prometheus: false + secrets-store: false + stash: true # enable if used + virtual-secrets: false + annotations: + "helm.sh/hook": null + "helm.sh/hook-delete-policy": null + repoURL: ghcr.io/appscode-charts + targetRevision: v2026.2.16 + syncPolicy: + automated: {} + syncOptions: + - CreateNamespace=true +``` + +### 2. Install license-proxyserver + +Save the following manifest as `license-proxyserver.yaml` and replace the `token` value with your AppsCode platform token, then apply it with `kubectl apply -f license-proxyserver.yaml`: + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: license-proxyserver + namespace: argocd +spec: + project: default + source: + chart: license-proxyserver + repoURL: ghcr.io/appscode-charts + targetRevision: v2026.2.16 + helm: + values: | + platform: + baseURL: https://appscode.com + token: '****************************************' + destination: + server: "https://kubernetes.default.svc" + namespace: kubeops + syncPolicy: + automated: {} + syncOptions: + - CreateNamespace=true + + ignoreDifferences: + - jsonPointers: + - /data + kind: Secret + name: license-proxyserver-apiserver-cert + namespace: kubeops + - group: apiregistration.k8s.io + kind: APIService + name: v1alpha1.proxyserver.licenses.appscode.com + jsonPointers: + - /spec/caBundle + - group: apiextensions.k8s.io + kind: CustomResourceDefinition + name: servicemonitors.monitoring.coreos.com + jsonPointers: + - /metadata/annotations + - /spec +``` + +The `ignoreDifferences` block prevents ArgoCD from continuously fighting the controllers that rotate the apiserver certificate, CA bundle, and ServiceMonitor CRD annotations. + +### 3. Install KubeStash + +Save the following manifest as `kubestash.yaml` and apply it with `kubectl apply -f kubestash.yaml`: + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: kubestash + namespace: argocd +spec: + project: default + source: + chart: kubestash + repoURL: ghcr.io/appscode-charts + targetRevision: {{< param "info.version" >}} + helm: + values: | + ace-user-roles: + enabled: false + destination: + server: "https://kubernetes.default.svc" + namespace: kubestash + syncPolicy: + automated: {} + syncOptions: + - CreateNamespace=true + + ignoreDifferences: + - jsonPointers: + - /data + kind: Secret + name: kubestash-kubestash-operator-cert + namespace: kubestash + - group: apps + kind: Deployment + name: kubestash-kubestash-operator-operator + namespace: kubestash + jsonPointers: + - /spec/template/metadata/annotations/reload + - group: apps + kind: Deployment + name: kubestash-kubestash-operator-webhook-server + namespace: kubestash + jsonPointers: + - /spec/template/metadata/annotations/reload + + - group: admissionregistration.k8s.io + kind: MutatingWebhookConfiguration + name: kubestash-kubestash-operator + jqPathExpressions: + - .webhooks[].clientConfig.caBundle + - group: admissionregistration.k8s.io + kind: ValidatingWebhookConfiguration + name: kubestash-kubestash-operator + jqPathExpressions: + - .webhooks[].clientConfig.caBundle +``` + +Notes: + +- `ace-user-roles.enabled: false` is set on the KubeStash Application because the `ace-user-roles` chart is already managed by its own Application (step 1). +- The `ignoreDifferences` entries cover the webhook CA bundles, operator TLS secret and the reload annotation that KubeStash flips when its configuration changes. Without them ArgoCD would report the Application as out-of-sync after every reconciliation. + +Once all three Applications are healthy, follow the [Verify installation](#verify-installation) steps above. + +## Install in OpenShift + +There are two ways to deploy KubeStash in [OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift). Use Option A for the standard upstream chart, or Option B if you require the Red Hat OpenShift certified chart (for example, to satisfy a Red Hat OpenShift certification requirement). + +### Option A: Standard chart with OpenShift values + +Use the same `kubestash` chart shown above and enable the OpenShift distribution values. This switches the operator to UBI-based images and applies the SecurityContextConstraints and other OpenShift-specific tweaks: + +```bash +$ helm install kubestash oci://ghcr.io/appscode-charts/kubestash \ + --version {{< param "info.version" >}} \ + --namespace stash --create-namespace \ + --set-file global.license=/path/to/the/license.txt \ + --set global.distro.openshift=true \ + --set global.distro.ubi=all \ + --wait --burst-limit=10000 --debug +``` + +Equivalently, in a `values.yaml`: + +```yaml +global: + distro: + openshift: true + ubi: "all" +``` + +- `global.distro.openshift: true` enables OpenShift-specific resources (SCCs, etc.). +- `global.distro.ubi: "all"` switches every component to UBI-based images. Set it to `operator` to only switch the operator images. + +### Option B: Red Hat OpenShift certified chart + +The `kubestash-certified` chart is the Red Hat certified distribution of KubeStash. Unlike the standard chart, **it does not include CRDs** — the certification process requires CRDs to ship as a separate chart. You must therefore install the CRDs chart first, and then the operator chart. + +#### Step 1: Install the CRDs + +```bash +$ helm install kubestash-certified-crds oci://ghcr.io/appscode-charts/kubestash-certified-crds \ + --version {{< param "info.version" >}} \ + --namespace stash --create-namespace \ + --wait --burst-limit=10000 --debug +``` + +#### Step 2: Install the certified operator chart + +```bash +$ helm install kubestash oci://ghcr.io/appscode-charts/kubestash-certified \ + --version {{< param "info.version" >}} \ + --namespace stash \ + --set-file global.license=/path/to/the/license.txt \ + --wait --burst-limit=10000 --debug +``` + +Once installed, follow the [Verify installation](#verify-installation) steps above to confirm the operator and Addon catalogs are running. + ## Purchase KubeStash License If you are interested in purchasing KubeStash 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). From 6e26cae9fc8797fea4d9d2eb0a5f32f22b581275 Mon Sep 17 00:00:00 2001 From: Tamal Saha Date: Fri, 12 Jun 2026 21:01:02 +0600 Subject: [PATCH 2/7] Add FluxCD install guide for KubeStash Document deploying KubeStash declaratively via FluxCD using an OCI HelmRepository for ghcr.io/appscode-charts and three HelmReleases for ace-user-roles, license-proxyserver and kubestash, mirroring the ArgoCD flow. Signed-off-by: Tamal Saha --- docs/setup/install/kubestash/index.md | 128 ++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) diff --git a/docs/setup/install/kubestash/index.md b/docs/setup/install/kubestash/index.md index 2ad13db..80d1628 100644 --- a/docs/setup/install/kubestash/index.md +++ b/docs/setup/install/kubestash/index.md @@ -288,6 +288,134 @@ Notes: Once all three Applications are healthy, follow the [Verify installation](#verify-installation) steps above. +## Install using FluxCD + +You can also deploy KubeStash declaratively with [FluxCD](https://fluxcd.io/). The setup mirrors the ArgoCD flow: one OCI `HelmRepository` pointing at `ghcr.io/appscode-charts`, followed by three `HelmRelease` resources installed in the same order — `ace-user-roles`, `license-proxyserver`, and `kubestash`. + +### Prerequisites + +- A cluster with the FluxCD `source-controller` and `helm-controller` installed (e.g. via `flux install` or `flux bootstrap`). +- An AppsCode platform token. Replace the placeholder `token` value in the `license-proxyserver` HelmRelease with your token. + +### 1. Register the AppsCode OCI Helm repository + +Save the following manifest as `appscode-charts.yaml` and apply it with `kubectl apply -f appscode-charts.yaml`: + +```yaml +apiVersion: source.toolkit.fluxcd.io/v1beta2 +kind: HelmRepository +metadata: + name: appscode-charts + namespace: flux-system +spec: + type: oci + interval: 5m + url: oci://ghcr.io/appscode-charts +``` + +### 2. Install ace-user-roles + +```yaml +apiVersion: helm.toolkit.fluxcd.io/v2 +kind: HelmRelease +metadata: + name: ace-user-roles + namespace: flux-system +spec: + interval: 10m + targetNamespace: kubeops + install: + createNamespace: true + chart: + spec: + chart: ace-user-roles + version: v2026.2.16 + sourceRef: + kind: HelmRepository + name: appscode-charts + namespace: flux-system + values: + enableClusterRoles: + ace: false + appcatalog: true + catalog: false + cert-manager: false + kubedb: true + kubedb-ui: false + kubestash: true # enable if used + kubevault: true # enable if used + license-proxyserver: true + metrics: true + prometheus: false + secrets-store: false + stash: true # enable if used + virtual-secrets: false + annotations: + "helm.sh/hook": null + "helm.sh/hook-delete-policy": null +``` + +### 3. Install license-proxyserver + +```yaml +apiVersion: helm.toolkit.fluxcd.io/v2 +kind: HelmRelease +metadata: + name: license-proxyserver + namespace: flux-system +spec: + interval: 10m + targetNamespace: kubeops + install: + createNamespace: true + chart: + spec: + chart: license-proxyserver + version: v2026.2.16 + sourceRef: + kind: HelmRepository + name: appscode-charts + namespace: flux-system + values: + platform: + baseURL: https://appscode.com + token: '****************************************' +``` + +### 4. Install KubeStash + +```yaml +apiVersion: helm.toolkit.fluxcd.io/v2 +kind: HelmRelease +metadata: + name: kubestash + namespace: flux-system +spec: + interval: 10m + targetNamespace: kubestash + install: + createNamespace: true + chart: + spec: + chart: kubestash + version: {{< param "info.version" >}} + sourceRef: + kind: HelmRepository + name: appscode-charts + namespace: flux-system + values: + ace-user-roles: + enabled: false +``` + +Notes: + +- The `HelmRepository` is created once in `flux-system` and reused by every `HelmRelease` via `sourceRef`. Adjust the `namespace` if you keep Flux sources elsewhere. +- `ace-user-roles.enabled: false` is set on the KubeStash HelmRelease because the `ace-user-roles` chart is already managed by its own HelmRelease (step 2). +- FluxCD's `helm-controller` reconciles by re-running `helm upgrade`, so unlike ArgoCD you do not need to declare `ignoreDifferences` for the operator's rotating TLS certs and webhook CA bundles. + +Once all three HelmReleases report `Ready`, follow the [Verify installation](#verify-installation) steps above. + ## Install in OpenShift There are two ways to deploy KubeStash in [OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift). Use Option A for the standard upstream chart, or Option B if you require the Red Hat OpenShift certified chart (for example, to satisfy a Red Hat OpenShift certification requirement). From 33321ba04c8c47268bedfbec6ac72fd6c277969f Mon Sep 17 00:00:00 2001 From: Tamal Saha Date: Tue, 16 Jun 2026 00:27:18 +0600 Subject: [PATCH 3/7] fix Signed-off-by: Tamal Saha --- .github/workflows/preview-website.yml | 2 +- docs/setup/uninstall/kubestash/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/preview-website.yml b/.github/workflows/preview-website.yml index 134e457..46979f6 100644 --- a/.github/workflows/preview-website.yml +++ b/.github/workflows/preview-website.yml @@ -41,7 +41,7 @@ jobs: - name: Install Hugo run: | - curl -fsSL -o hugo_extended.deb https://github.com/gohugoio/hugo/releases/download/v0.111.1/hugo_extended_0.111.1_linux-amd64.deb + curl -fsSL -o hugo_extended.deb https://github.com/gohugoio/hugo/releases/download/v0.128.2/hugo_extended_0.128.2_linux-amd64.deb sudo dpkg -i hugo_extended.deb rm hugo_extended.deb diff --git a/docs/setup/uninstall/kubestash/index.md b/docs/setup/uninstall/kubestash/index.md index c6ec337..c15f9a9 100644 --- a/docs/setup/uninstall/kubestash/index.md +++ b/docs/setup/uninstall/kubestash/index.md @@ -29,7 +29,7 @@ To uninstall KubeStash, run the following command: ## Using Helm 3 -In Helm 3, release names are [scoped to a namespace](https://v3.helm.sh/docs/faq/#release-names-are-now-scoped-to-the-namespace). So, provide the namespace you used to install the operator when installing. +In Helm 3, release names are [scoped to a namespace](https://helm.sh/docs/v3/faq/changes_since_helm2/). So, provide the namespace you used to install the operator when installing. ```bash $ helm uninstall kubestash --namespace stash From b6fbf520eb6e01399dce1d6aeaca459939b9d2c7 Mon Sep 17 00:00:00 2001 From: Arnob Kumar Saha Date: Tue, 16 Jun 2026 11:11:21 +0600 Subject: [PATCH 4/7] Restructure KubeStash install docs into per-method pages Split the single setup/install/kubestash/index.md into a section with one page per installation method (Helm, YAML, ArgoCD, FluxCD, OpenShift) plus a common configuration page holding the verify steps, mirroring kubedb/docs#885. Repoint referencing pages to the new _index.md. Signed-off-by: Arnob Kumar Saha --- docs/README.md | 2 +- .../hooks/backup-and-restore-hooks/index.md | 2 +- docs/guides/hooks/slack-notification/index.md | 2 +- docs/setup/README.md | 4 +- docs/setup/install/kubestash/_index.md | 39 ++ docs/setup/install/kubestash/argocd.md | 187 +++++++ docs/setup/install/kubestash/configuration.md | 63 +++ docs/setup/install/kubestash/fluxcd.md | 141 ++++++ docs/setup/install/kubestash/helm.md | 29 ++ docs/setup/install/kubestash/index.md | 478 ------------------ docs/setup/install/kubestash/openshift.md | 68 +++ docs/setup/install/kubestash/yaml.md | 28 + 12 files changed, 560 insertions(+), 483 deletions(-) create mode 100644 docs/setup/install/kubestash/_index.md create mode 100644 docs/setup/install/kubestash/argocd.md create mode 100644 docs/setup/install/kubestash/configuration.md create mode 100644 docs/setup/install/kubestash/fluxcd.md create mode 100644 docs/setup/install/kubestash/helm.md delete mode 100644 docs/setup/install/kubestash/index.md create mode 100644 docs/setup/install/kubestash/openshift.md create mode 100644 docs/setup/install/kubestash/yaml.md diff --git a/docs/README.md b/docs/README.md index a1e877e..9fa5fb0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -35,7 +35,7 @@ Concept explains some significant aspect of KubeStash. This is where you can lea Setup contains instruction for installing, uninstalling, and upgrading KubeStash. - **Install KubeStash:** Provides installation instructions for KubeStash and its various components. - - [KubeStash](/docs/setup/install/kubestash/index.md): Provides installation instructions for KubeStash. + - [KubeStash](/docs/setup/install/kubestash/_index.md): Provides installation instructions for KubeStash. - [kubeStash kubectl Plugin](/docs/setup/install/kubectl-plugin/index.md): Provides installation instructions for KubeStash `kubectl` plugin. - [Troubleshooting](/docs/setup/install/troubleshooting/index.md): Provides troubleshooting guide for various installation problems. - **Uninstall KubeStash:** Provides uninstallation instructions for KubeStash and its various components. diff --git a/docs/guides/hooks/backup-and-restore-hooks/index.md b/docs/guides/hooks/backup-and-restore-hooks/index.md index 807904b..b018ab2 100644 --- a/docs/guides/hooks/backup-and-restore-hooks/index.md +++ b/docs/guides/hooks/backup-and-restore-hooks/index.md @@ -22,7 +22,7 @@ Here, we are going to demonstrate how you can perform different actions before a ## Before You Begin - At first, you need to have a Kubernetes cluster, and the `kubectl` command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). -- Install KubeStash in your cluster following the steps [here](/docs/setup/install/kubestash/index.md). +- Install KubeStash in your cluster following the steps [here](/docs/setup/install/kubestash/_index.md). - Install [KubeDB](https://kubedb.com) in your cluster following the steps [here](https://kubedb.com/docs/latest/setup/). This step is optional. You can deploy your database using any method you want. We are using KubeDB because KubeDB simplifies many of the difficult or tedious management tasks of running production-grade databases on private and public clouds. - If you are not familiar with how KubeStash backup and restore MySQL databases, please check the [KubeDB](https://kubedb.com/) documentation for MySQL backup and restore using KubeStash. - Also, if you haven't read about how hooks work in KubeStash, please check it from [here](/docs/guides/hooks/overview/index.md). diff --git a/docs/guides/hooks/slack-notification/index.md b/docs/guides/hooks/slack-notification/index.md index 4160b58..3859bc4 100644 --- a/docs/guides/hooks/slack-notification/index.md +++ b/docs/guides/hooks/slack-notification/index.md @@ -18,7 +18,7 @@ In this guide, we are going to show you how to send backup notifications to a Sl ## Before You Begin - At first, you need to have a Kubernetes cluster, and the `kubectl` command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). -- Install KubeStash in your cluster following the steps [here](/docs/setup/install/kubestash/index.md). +- Install KubeStash in your cluster following the steps [here](/docs/setup/install/kubestash/_index.md). - If you haven't read about how hooks work in KubeStash, please check it from [here](/docs/guides/hooks/overview/index.md). You should be familiar with the following `KubeStash` concepts: diff --git a/docs/setup/README.md b/docs/setup/README.md index 4f0e703..c315b8a 100644 --- a/docs/setup/README.md +++ b/docs/setup/README.md @@ -18,14 +18,14 @@ aliases: # 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. - - [KubeStash operator](/docs/setup/install/kubestash/index.md): Installation instructions for KubeStash operator. + - [KubeStash operator](/docs/setup/install/kubestash/_index.md): Installation instructions for KubeStash operator. - [KubeStash kubectl Plugin](/docs/setup/install/kubectl-plugin/index.md): Installation instructions for kubeStash `kubectl` plugin. - [Troubleshooting](/docs/setup/install/troubleshooting/index.md): Troubleshooting guide for various installation problems. diff --git a/docs/setup/install/kubestash/_index.md b/docs/setup/install/kubestash/_index.md new file mode 100644 index 0000000..b66f06c --- /dev/null +++ b/docs/setup/install/kubestash/_index.md @@ -0,0 +1,39 @@ +--- +title: Install KubeStash +description: Installation guide for KubeStash +menu: + docs_{{ .version }}: + identifier: install-kubestash-enterprise + name: KubeStash + parent: installation-guide + weight: 20 +product_name: kubestash +menu_name: docs_{{ .version }} +section_menu_id: setup +--- + +# Install KubeStash + +## 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). + +## Choose an Installation Method + +KubeStash can be installed in several ways. Pick the one that fits your workflow: + +- [Helm 3](/docs/setup/install/kubestash/helm/) — recommended for most users. +- [YAML](/docs/setup/install/kubestash/yaml/) — render manifests and apply with `kubectl`. +- [ArgoCD](/docs/setup/install/kubestash/argocd/) — GitOps via ArgoCD `Application` resources. +- [FluxCD](/docs/setup/install/kubestash/fluxcd/) — GitOps via the Flux Helm Controller. +- [OpenShift](/docs/setup/install/kubestash/openshift/) — standard chart or Red Hat certified chart. + +After installing, see [Common Configuration](/docs/setup/install/kubestash/configuration/) to verify the installation. + +## Purchase KubeStash License + +If you are interested in purchasing KubeStash 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 KubeStash 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/kubestash/argocd.md b/docs/setup/install/kubestash/argocd.md new file mode 100644 index 0000000..4a3e397 --- /dev/null +++ b/docs/setup/install/kubestash/argocd.md @@ -0,0 +1,187 @@ +--- +title: Install KubeStash using ArgoCD +description: Install KubeStash using ArgoCD +menu: + docs_{{ .version }}: + identifier: install-kubestash-argocd + name: ArgoCD + parent: install-kubestash-enterprise + weight: 30 +product_name: kubestash +menu_name: docs_{{ .version }} +section_menu_id: setup +--- + +# Install using ArgoCD + +You can deploy KubeStash declaratively using [ArgoCD](https://argo-cd.readthedocs.io/). The setup is composed of three `Application` manifests that should be applied in the following order: + +1. `ace-user-roles` — installs the ClusterRoles used by KubeStash (and other AppsCode products) so that user impersonation works correctly. +2. `license-proxyserver` — installs the AppsCode License Proxyserver, which obtains and rotates the KubeStash license from the AppsCode platform automatically. You no longer need to download a license file when this is used. +3. `kubestash` — installs the KubeStash operator itself. + +### Prerequisites + +- An ArgoCD installation reachable at the `argocd` namespace. +- An AppsCode platform token. You can obtain one from the [AppsCode platform](https://appscode.com/). Replace the placeholder value in the `license-proxyserver` manifest with your token. + +### 1. Install ace-user-roles + +Save the following manifest as `ace-user-roles.yaml` and apply it with `kubectl apply -f ace-user-roles.yaml`: + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: ace-user-roles + namespace: argocd +spec: + destination: + namespace: kubeops + server: https://kubernetes.default.svc + project: default + source: + chart: ace-user-roles + helm: + values: | + enableClusterRoles: + ace: false + appcatalog: true + catalog: false + cert-manager: false + kubedb: true + kubedb-ui: false + kubestash: true # enable if used + kubevault: true # enable if used + license-proxyserver: true + metrics: true + prometheus: false + secrets-store: false + stash: true # enable if used + virtual-secrets: false + annotations: + "helm.sh/hook": null + "helm.sh/hook-delete-policy": null + repoURL: ghcr.io/appscode-charts + targetRevision: v2026.2.16 + syncPolicy: + automated: {} + syncOptions: + - CreateNamespace=true +``` + +### 2. Install license-proxyserver + +Save the following manifest as `license-proxyserver.yaml` and replace the `token` value with your AppsCode platform token, then apply it with `kubectl apply -f license-proxyserver.yaml`: + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: license-proxyserver + namespace: argocd +spec: + project: default + source: + chart: license-proxyserver + repoURL: ghcr.io/appscode-charts + targetRevision: v2026.2.16 + helm: + values: | + platform: + baseURL: https://appscode.com + token: '****************************************' + destination: + server: "https://kubernetes.default.svc" + namespace: kubeops + syncPolicy: + automated: {} + syncOptions: + - CreateNamespace=true + + ignoreDifferences: + - jsonPointers: + - /data + kind: Secret + name: license-proxyserver-apiserver-cert + namespace: kubeops + - group: apiregistration.k8s.io + kind: APIService + name: v1alpha1.proxyserver.licenses.appscode.com + jsonPointers: + - /spec/caBundle + - group: apiextensions.k8s.io + kind: CustomResourceDefinition + name: servicemonitors.monitoring.coreos.com + jsonPointers: + - /metadata/annotations + - /spec +``` + +The `ignoreDifferences` block prevents ArgoCD from continuously fighting the controllers that rotate the apiserver certificate, CA bundle, and ServiceMonitor CRD annotations. + +### 3. Install KubeStash + +Save the following manifest as `kubestash.yaml` and apply it with `kubectl apply -f kubestash.yaml`: + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: kubestash + namespace: argocd +spec: + project: default + source: + chart: kubestash + repoURL: ghcr.io/appscode-charts + targetRevision: {{< param "info.version" >}} + helm: + values: | + ace-user-roles: + enabled: false + destination: + server: "https://kubernetes.default.svc" + namespace: kubestash + syncPolicy: + automated: {} + syncOptions: + - CreateNamespace=true + + ignoreDifferences: + - jsonPointers: + - /data + kind: Secret + name: kubestash-kubestash-operator-cert + namespace: kubestash + - group: apps + kind: Deployment + name: kubestash-kubestash-operator-operator + namespace: kubestash + jsonPointers: + - /spec/template/metadata/annotations/reload + - group: apps + kind: Deployment + name: kubestash-kubestash-operator-webhook-server + namespace: kubestash + jsonPointers: + - /spec/template/metadata/annotations/reload + + - group: admissionregistration.k8s.io + kind: MutatingWebhookConfiguration + name: kubestash-kubestash-operator + jqPathExpressions: + - .webhooks[].clientConfig.caBundle + - group: admissionregistration.k8s.io + kind: ValidatingWebhookConfiguration + name: kubestash-kubestash-operator + jqPathExpressions: + - .webhooks[].clientConfig.caBundle +``` + +Notes: + +- `ace-user-roles.enabled: false` is set on the KubeStash Application because the `ace-user-roles` chart is already managed by its own Application (step 1). +- The `ignoreDifferences` entries cover the webhook CA bundles, operator TLS secret and the reload annotation that KubeStash flips when its configuration changes. Without them ArgoCD would report the Application as out-of-sync after every reconciliation. + +Once all three Applications are healthy, follow the [verify the installation](/docs/setup/install/kubestash/configuration/) steps. diff --git a/docs/setup/install/kubestash/configuration.md b/docs/setup/install/kubestash/configuration.md new file mode 100644 index 0000000..eb399bb --- /dev/null +++ b/docs/setup/install/kubestash/configuration.md @@ -0,0 +1,63 @@ +--- +title: KubeStash Common Configuration +description: Verify the KubeStash installation +menu: + docs_{{ .version }}: + identifier: install-kubestash-config + name: Common Configuration + parent: install-kubestash-enterprise + weight: 60 +product_name: kubestash +menu_name: docs_{{ .version }} +section_menu_id: setup +--- + +# Common Configuration + +The steps below apply regardless of which [installation method](/docs/setup/install/kubestash/) you used. + +## 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 +stash 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 Catalogs + +KubeStash automatically installs the necessary Addon catalogs for workload, PVC and Kubernetes manifest backups. Verify that the Addon catalogs have been installed using the following command. + +```bash +$ kubectl get addons.addons.kubestash.com +NAME AGE +kubedump-addon 7m1s +pvc-addon 7m1s +workload-addon 7m1s +``` + +As you can see from the above output that KubeStash has created `Addon` objects. + +Now, you are ready to [take your first backup](/docs/guides/README.md) using KubeStash. diff --git a/docs/setup/install/kubestash/fluxcd.md b/docs/setup/install/kubestash/fluxcd.md new file mode 100644 index 0000000..36009be --- /dev/null +++ b/docs/setup/install/kubestash/fluxcd.md @@ -0,0 +1,141 @@ +--- +title: Install KubeStash using FluxCD +description: Install KubeStash using FluxCD +menu: + docs_{{ .version }}: + identifier: install-kubestash-fluxcd + name: FluxCD + parent: install-kubestash-enterprise + weight: 40 +product_name: kubestash +menu_name: docs_{{ .version }} +section_menu_id: setup +--- + +# Install using FluxCD + +You can also deploy KubeStash declaratively with [FluxCD](https://fluxcd.io/). The setup mirrors the ArgoCD flow: one OCI `HelmRepository` pointing at `ghcr.io/appscode-charts`, followed by three `HelmRelease` resources installed in the same order — `ace-user-roles`, `license-proxyserver`, and `kubestash`. + +### Prerequisites + +- A cluster with the FluxCD `source-controller` and `helm-controller` installed (e.g. via `flux install` or `flux bootstrap`). +- An AppsCode platform token. Replace the placeholder `token` value in the `license-proxyserver` HelmRelease with your token. + +### 1. Register the AppsCode OCI Helm repository + +Save the following manifest as `appscode-charts.yaml` and apply it with `kubectl apply -f appscode-charts.yaml`: + +```yaml +apiVersion: source.toolkit.fluxcd.io/v1beta2 +kind: HelmRepository +metadata: + name: appscode-charts + namespace: flux-system +spec: + type: oci + interval: 5m + url: oci://ghcr.io/appscode-charts +``` + +### 2. Install ace-user-roles + +```yaml +apiVersion: helm.toolkit.fluxcd.io/v2 +kind: HelmRelease +metadata: + name: ace-user-roles + namespace: flux-system +spec: + interval: 10m + targetNamespace: kubeops + install: + createNamespace: true + chart: + spec: + chart: ace-user-roles + version: v2026.2.16 + sourceRef: + kind: HelmRepository + name: appscode-charts + namespace: flux-system + values: + enableClusterRoles: + ace: false + appcatalog: true + catalog: false + cert-manager: false + kubedb: true + kubedb-ui: false + kubestash: true # enable if used + kubevault: true # enable if used + license-proxyserver: true + metrics: true + prometheus: false + secrets-store: false + stash: true # enable if used + virtual-secrets: false + annotations: + "helm.sh/hook": null + "helm.sh/hook-delete-policy": null +``` + +### 3. Install license-proxyserver + +```yaml +apiVersion: helm.toolkit.fluxcd.io/v2 +kind: HelmRelease +metadata: + name: license-proxyserver + namespace: flux-system +spec: + interval: 10m + targetNamespace: kubeops + install: + createNamespace: true + chart: + spec: + chart: license-proxyserver + version: v2026.2.16 + sourceRef: + kind: HelmRepository + name: appscode-charts + namespace: flux-system + values: + platform: + baseURL: https://appscode.com + token: '****************************************' +``` + +### 4. Install KubeStash + +```yaml +apiVersion: helm.toolkit.fluxcd.io/v2 +kind: HelmRelease +metadata: + name: kubestash + namespace: flux-system +spec: + interval: 10m + targetNamespace: kubestash + install: + createNamespace: true + chart: + spec: + chart: kubestash + version: {{< param "info.version" >}} + sourceRef: + kind: HelmRepository + name: appscode-charts + namespace: flux-system + values: + ace-user-roles: + enabled: false +``` + +Notes: + +- The `HelmRepository` is created once in `flux-system` and reused by every `HelmRelease` via `sourceRef`. Adjust the `namespace` if you keep Flux sources elsewhere. +- `ace-user-roles.enabled: false` is set on the KubeStash HelmRelease because the `ace-user-roles` chart is already managed by its own HelmRelease (step 2). +- FluxCD's `helm-controller` reconciles by re-running `helm upgrade`, so unlike ArgoCD you do not need to declare `ignoreDifferences` for the operator's rotating TLS certs and webhook CA bundles. + +Once all three HelmReleases report `Ready`, follow the [verify the installation](/docs/setup/install/kubestash/configuration/) steps. diff --git a/docs/setup/install/kubestash/helm.md b/docs/setup/install/kubestash/helm.md new file mode 100644 index 0000000..fbc65a2 --- /dev/null +++ b/docs/setup/install/kubestash/helm.md @@ -0,0 +1,29 @@ +--- +title: Install KubeStash using Helm 3 +description: Install KubeStash using Helm 3 +menu: + docs_{{ .version }}: + identifier: install-kubestash-helm + name: Helm 3 + parent: install-kubestash-enterprise + weight: 10 +product_name: kubestash +menu_name: docs_{{ .version }} +section_menu_id: setup +--- + +# Using Helm 3 + +KubeStash can be installed via [Helm](https://helm.sh/) using the [chart](https://github.com/kubestash/installer/tree/master/charts/kubestash) from [AppsCode Charts Repository](https://github.com/appscode/charts). To install the chart with the release name `kubestash`: + +```bash +$ helm install kubestash oci://ghcr.io/appscode-charts/kubestash \ + --version {{< param "info.version" >}} \ + --namespace stash --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/master/charts/kubestash). + +Next: [verify the installation](/docs/setup/install/kubestash/configuration/). diff --git a/docs/setup/install/kubestash/index.md b/docs/setup/install/kubestash/index.md deleted file mode 100644 index 80d1628..0000000 --- a/docs/setup/install/kubestash/index.md +++ /dev/null @@ -1,478 +0,0 @@ ---- -title: Install KubeStash -description: Installation guide for KubeStash -menu: - docs_{{ .version }}: - identifier: install-kubestash-enterprise - name: KubeStash - parent: installation-guide - weight: 20 -product_name: kubestash -menu_name: docs_{{ .version }} -section_menu_id: setup ---- - -# Install KubeStash - -## 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 - -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](https://github.com/kubestash/installer/tree/master/charts/kubestash) from [AppsCode Charts Repository](https://github.com/appscode/charts). To install the chart with the release name `kubestash`: - -```bash -$ helm install kubestash oci://ghcr.io/appscode-charts/kubestash \ - --version {{< param "info.version" >}} \ - --namespace stash --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/master/charts/kubestash). - -
-
- -### 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 template kubestash oci://ghcr.io/appscode-charts/kubestash \ - --version {{< param "info.version" >}} \ - --namespace stash --create-namespace \ - --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/master/charts/kubestash). - -
-
- -### 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 -stash 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 Catalogs - -KubeStash automatically installs the necessary Addon catalogs for workload, PVC and Kubernetes manifest backups. Verify that the Addon catalogs have been installed using the following command. - -```bash -$ kubectl get addons.addons.kubestash.com -NAME AGE -kubedump-addon 7m1s -pvc-addon 7m1s -workload-addon 7m1s -``` - -As you can see from the above output that KubeStash has created `Addon` objects. - -Now, you are ready to [take your first backup](/docs/guides/README.md) using KubeStash. - -## Install using ArgoCD - -You can deploy KubeStash declaratively using [ArgoCD](https://argo-cd.readthedocs.io/). The setup is composed of three `Application` manifests that should be applied in the following order: - -1. `ace-user-roles` — installs the ClusterRoles used by KubeStash (and other AppsCode products) so that user impersonation works correctly. -2. `license-proxyserver` — installs the AppsCode License Proxyserver, which obtains and rotates the KubeStash license from the AppsCode platform automatically. You no longer need to download a license file when this is used. -3. `kubestash` — installs the KubeStash operator itself. - -### Prerequisites - -- An ArgoCD installation reachable at the `argocd` namespace. -- An AppsCode platform token. You can obtain one from the [AppsCode platform](https://appscode.com/). Replace the placeholder value in the `license-proxyserver` manifest with your token. - -### 1. Install ace-user-roles - -Save the following manifest as `ace-user-roles.yaml` and apply it with `kubectl apply -f ace-user-roles.yaml`: - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - name: ace-user-roles - namespace: argocd -spec: - destination: - namespace: kubeops - server: https://kubernetes.default.svc - project: default - source: - chart: ace-user-roles - helm: - values: | - enableClusterRoles: - ace: false - appcatalog: true - catalog: false - cert-manager: false - kubedb: true - kubedb-ui: false - kubestash: true # enable if used - kubevault: true # enable if used - license-proxyserver: true - metrics: true - prometheus: false - secrets-store: false - stash: true # enable if used - virtual-secrets: false - annotations: - "helm.sh/hook": null - "helm.sh/hook-delete-policy": null - repoURL: ghcr.io/appscode-charts - targetRevision: v2026.2.16 - syncPolicy: - automated: {} - syncOptions: - - CreateNamespace=true -``` - -### 2. Install license-proxyserver - -Save the following manifest as `license-proxyserver.yaml` and replace the `token` value with your AppsCode platform token, then apply it with `kubectl apply -f license-proxyserver.yaml`: - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - name: license-proxyserver - namespace: argocd -spec: - project: default - source: - chart: license-proxyserver - repoURL: ghcr.io/appscode-charts - targetRevision: v2026.2.16 - helm: - values: | - platform: - baseURL: https://appscode.com - token: '****************************************' - destination: - server: "https://kubernetes.default.svc" - namespace: kubeops - syncPolicy: - automated: {} - syncOptions: - - CreateNamespace=true - - ignoreDifferences: - - jsonPointers: - - /data - kind: Secret - name: license-proxyserver-apiserver-cert - namespace: kubeops - - group: apiregistration.k8s.io - kind: APIService - name: v1alpha1.proxyserver.licenses.appscode.com - jsonPointers: - - /spec/caBundle - - group: apiextensions.k8s.io - kind: CustomResourceDefinition - name: servicemonitors.monitoring.coreos.com - jsonPointers: - - /metadata/annotations - - /spec -``` - -The `ignoreDifferences` block prevents ArgoCD from continuously fighting the controllers that rotate the apiserver certificate, CA bundle, and ServiceMonitor CRD annotations. - -### 3. Install KubeStash - -Save the following manifest as `kubestash.yaml` and apply it with `kubectl apply -f kubestash.yaml`: - -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - name: kubestash - namespace: argocd -spec: - project: default - source: - chart: kubestash - repoURL: ghcr.io/appscode-charts - targetRevision: {{< param "info.version" >}} - helm: - values: | - ace-user-roles: - enabled: false - destination: - server: "https://kubernetes.default.svc" - namespace: kubestash - syncPolicy: - automated: {} - syncOptions: - - CreateNamespace=true - - ignoreDifferences: - - jsonPointers: - - /data - kind: Secret - name: kubestash-kubestash-operator-cert - namespace: kubestash - - group: apps - kind: Deployment - name: kubestash-kubestash-operator-operator - namespace: kubestash - jsonPointers: - - /spec/template/metadata/annotations/reload - - group: apps - kind: Deployment - name: kubestash-kubestash-operator-webhook-server - namespace: kubestash - jsonPointers: - - /spec/template/metadata/annotations/reload - - - group: admissionregistration.k8s.io - kind: MutatingWebhookConfiguration - name: kubestash-kubestash-operator - jqPathExpressions: - - .webhooks[].clientConfig.caBundle - - group: admissionregistration.k8s.io - kind: ValidatingWebhookConfiguration - name: kubestash-kubestash-operator - jqPathExpressions: - - .webhooks[].clientConfig.caBundle -``` - -Notes: - -- `ace-user-roles.enabled: false` is set on the KubeStash Application because the `ace-user-roles` chart is already managed by its own Application (step 1). -- The `ignoreDifferences` entries cover the webhook CA bundles, operator TLS secret and the reload annotation that KubeStash flips when its configuration changes. Without them ArgoCD would report the Application as out-of-sync after every reconciliation. - -Once all three Applications are healthy, follow the [Verify installation](#verify-installation) steps above. - -## Install using FluxCD - -You can also deploy KubeStash declaratively with [FluxCD](https://fluxcd.io/). The setup mirrors the ArgoCD flow: one OCI `HelmRepository` pointing at `ghcr.io/appscode-charts`, followed by three `HelmRelease` resources installed in the same order — `ace-user-roles`, `license-proxyserver`, and `kubestash`. - -### Prerequisites - -- A cluster with the FluxCD `source-controller` and `helm-controller` installed (e.g. via `flux install` or `flux bootstrap`). -- An AppsCode platform token. Replace the placeholder `token` value in the `license-proxyserver` HelmRelease with your token. - -### 1. Register the AppsCode OCI Helm repository - -Save the following manifest as `appscode-charts.yaml` and apply it with `kubectl apply -f appscode-charts.yaml`: - -```yaml -apiVersion: source.toolkit.fluxcd.io/v1beta2 -kind: HelmRepository -metadata: - name: appscode-charts - namespace: flux-system -spec: - type: oci - interval: 5m - url: oci://ghcr.io/appscode-charts -``` - -### 2. Install ace-user-roles - -```yaml -apiVersion: helm.toolkit.fluxcd.io/v2 -kind: HelmRelease -metadata: - name: ace-user-roles - namespace: flux-system -spec: - interval: 10m - targetNamespace: kubeops - install: - createNamespace: true - chart: - spec: - chart: ace-user-roles - version: v2026.2.16 - sourceRef: - kind: HelmRepository - name: appscode-charts - namespace: flux-system - values: - enableClusterRoles: - ace: false - appcatalog: true - catalog: false - cert-manager: false - kubedb: true - kubedb-ui: false - kubestash: true # enable if used - kubevault: true # enable if used - license-proxyserver: true - metrics: true - prometheus: false - secrets-store: false - stash: true # enable if used - virtual-secrets: false - annotations: - "helm.sh/hook": null - "helm.sh/hook-delete-policy": null -``` - -### 3. Install license-proxyserver - -```yaml -apiVersion: helm.toolkit.fluxcd.io/v2 -kind: HelmRelease -metadata: - name: license-proxyserver - namespace: flux-system -spec: - interval: 10m - targetNamespace: kubeops - install: - createNamespace: true - chart: - spec: - chart: license-proxyserver - version: v2026.2.16 - sourceRef: - kind: HelmRepository - name: appscode-charts - namespace: flux-system - values: - platform: - baseURL: https://appscode.com - token: '****************************************' -``` - -### 4. Install KubeStash - -```yaml -apiVersion: helm.toolkit.fluxcd.io/v2 -kind: HelmRelease -metadata: - name: kubestash - namespace: flux-system -spec: - interval: 10m - targetNamespace: kubestash - install: - createNamespace: true - chart: - spec: - chart: kubestash - version: {{< param "info.version" >}} - sourceRef: - kind: HelmRepository - name: appscode-charts - namespace: flux-system - values: - ace-user-roles: - enabled: false -``` - -Notes: - -- The `HelmRepository` is created once in `flux-system` and reused by every `HelmRelease` via `sourceRef`. Adjust the `namespace` if you keep Flux sources elsewhere. -- `ace-user-roles.enabled: false` is set on the KubeStash HelmRelease because the `ace-user-roles` chart is already managed by its own HelmRelease (step 2). -- FluxCD's `helm-controller` reconciles by re-running `helm upgrade`, so unlike ArgoCD you do not need to declare `ignoreDifferences` for the operator's rotating TLS certs and webhook CA bundles. - -Once all three HelmReleases report `Ready`, follow the [Verify installation](#verify-installation) steps above. - -## Install in OpenShift - -There are two ways to deploy KubeStash in [OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift). Use Option A for the standard upstream chart, or Option B if you require the Red Hat OpenShift certified chart (for example, to satisfy a Red Hat OpenShift certification requirement). - -### Option A: Standard chart with OpenShift values - -Use the same `kubestash` chart shown above and enable the OpenShift distribution values. This switches the operator to UBI-based images and applies the SecurityContextConstraints and other OpenShift-specific tweaks: - -```bash -$ helm install kubestash oci://ghcr.io/appscode-charts/kubestash \ - --version {{< param "info.version" >}} \ - --namespace stash --create-namespace \ - --set-file global.license=/path/to/the/license.txt \ - --set global.distro.openshift=true \ - --set global.distro.ubi=all \ - --wait --burst-limit=10000 --debug -``` - -Equivalently, in a `values.yaml`: - -```yaml -global: - distro: - openshift: true - ubi: "all" -``` - -- `global.distro.openshift: true` enables OpenShift-specific resources (SCCs, etc.). -- `global.distro.ubi: "all"` switches every component to UBI-based images. Set it to `operator` to only switch the operator images. - -### Option B: Red Hat OpenShift certified chart - -The `kubestash-certified` chart is the Red Hat certified distribution of KubeStash. Unlike the standard chart, **it does not include CRDs** — the certification process requires CRDs to ship as a separate chart. You must therefore install the CRDs chart first, and then the operator chart. - -#### Step 1: Install the CRDs - -```bash -$ helm install kubestash-certified-crds oci://ghcr.io/appscode-charts/kubestash-certified-crds \ - --version {{< param "info.version" >}} \ - --namespace stash --create-namespace \ - --wait --burst-limit=10000 --debug -``` - -#### Step 2: Install the certified operator chart - -```bash -$ helm install kubestash oci://ghcr.io/appscode-charts/kubestash-certified \ - --version {{< param "info.version" >}} \ - --namespace stash \ - --set-file global.license=/path/to/the/license.txt \ - --wait --burst-limit=10000 --debug -``` - -Once installed, follow the [Verify installation](#verify-installation) steps above to confirm the operator and Addon catalogs are running. - -## Purchase KubeStash License - -If you are interested in purchasing KubeStash 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 KubeStash 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/kubestash/openshift.md b/docs/setup/install/kubestash/openshift.md new file mode 100644 index 0000000..074f0ad --- /dev/null +++ b/docs/setup/install/kubestash/openshift.md @@ -0,0 +1,68 @@ +--- +title: Install KubeStash on OpenShift +description: Install KubeStash on OpenShift +menu: + docs_{{ .version }}: + identifier: install-kubestash-openshift + name: OpenShift + parent: install-kubestash-enterprise + weight: 50 +product_name: kubestash +menu_name: docs_{{ .version }} +section_menu_id: setup +--- + +# Install in OpenShift + +There are two ways to deploy KubeStash in [OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift). Use Option A for the standard upstream chart, or Option B if you require the Red Hat OpenShift certified chart (for example, to satisfy a Red Hat OpenShift certification requirement). + +### Option A: Standard chart with OpenShift values + +Use the same `kubestash` chart shown above and enable the OpenShift distribution values. This switches the operator to UBI-based images and applies the SecurityContextConstraints and other OpenShift-specific tweaks: + +```bash +$ helm install kubestash oci://ghcr.io/appscode-charts/kubestash \ + --version {{< param "info.version" >}} \ + --namespace stash --create-namespace \ + --set-file global.license=/path/to/the/license.txt \ + --set global.distro.openshift=true \ + --set global.distro.ubi=all \ + --wait --burst-limit=10000 --debug +``` + +Equivalently, in a `values.yaml`: + +```yaml +global: + distro: + openshift: true + ubi: "all" +``` + +- `global.distro.openshift: true` enables OpenShift-specific resources (SCCs, etc.). +- `global.distro.ubi: "all"` switches every component to UBI-based images. Set it to `operator` to only switch the operator images. + +### Option B: Red Hat OpenShift certified chart + +The `kubestash-certified` chart is the Red Hat certified distribution of KubeStash. Unlike the standard chart, **it does not include CRDs** — the certification process requires CRDs to ship as a separate chart. You must therefore install the CRDs chart first, and then the operator chart. + +#### Step 1: Install the CRDs + +```bash +$ helm install kubestash-certified-crds oci://ghcr.io/appscode-charts/kubestash-certified-crds \ + --version {{< param "info.version" >}} \ + --namespace stash --create-namespace \ + --wait --burst-limit=10000 --debug +``` + +#### Step 2: Install the certified operator chart + +```bash +$ helm install kubestash oci://ghcr.io/appscode-charts/kubestash-certified \ + --version {{< param "info.version" >}} \ + --namespace stash \ + --set-file global.license=/path/to/the/license.txt \ + --wait --burst-limit=10000 --debug +``` + +Once installed, follow the [verify the installation](/docs/setup/install/kubestash/configuration/) steps to confirm the operator and Addon catalogs are running. diff --git a/docs/setup/install/kubestash/yaml.md b/docs/setup/install/kubestash/yaml.md new file mode 100644 index 0000000..8ab2472 --- /dev/null +++ b/docs/setup/install/kubestash/yaml.md @@ -0,0 +1,28 @@ +--- +title: Install KubeStash using YAML +description: Install KubeStash using YAML +menu: + docs_{{ .version }}: + identifier: install-kubestash-yaml + name: YAML + parent: install-kubestash-enterprise + weight: 20 +product_name: kubestash +menu_name: docs_{{ .version }} +section_menu_id: setup +--- + +# 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 template kubestash oci://ghcr.io/appscode-charts/kubestash \ + --version {{< param "info.version" >}} \ + --namespace stash --create-namespace \ + --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/master/charts/kubestash). + +Next: [verify the installation](/docs/setup/install/kubestash/configuration/). From 1049893c3756da745874f68c8b30111b9a7aa284 Mon Sep 17 00:00:00 2001 From: Arnob Kumar Saha Date: Tue, 16 Jun 2026 11:14:16 +0600 Subject: [PATCH 5/7] Fix typo, stale cross-ref, and link phrasing in install docs - yaml.md: prodecure -> procedure - openshift.md: replace 'chart shown above' with a link to the Helm page - argocd/fluxcd/openshift: reword the verify link to Common Configuration Signed-off-by: Arnob Kumar Saha --- docs/setup/install/kubestash/argocd.md | 2 +- docs/setup/install/kubestash/fluxcd.md | 2 +- docs/setup/install/kubestash/openshift.md | 4 ++-- docs/setup/install/kubestash/yaml.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/setup/install/kubestash/argocd.md b/docs/setup/install/kubestash/argocd.md index 4a3e397..f45c563 100644 --- a/docs/setup/install/kubestash/argocd.md +++ b/docs/setup/install/kubestash/argocd.md @@ -184,4 +184,4 @@ Notes: - `ace-user-roles.enabled: false` is set on the KubeStash Application because the `ace-user-roles` chart is already managed by its own Application (step 1). - The `ignoreDifferences` entries cover the webhook CA bundles, operator TLS secret and the reload annotation that KubeStash flips when its configuration changes. Without them ArgoCD would report the Application as out-of-sync after every reconciliation. -Once all three Applications are healthy, follow the [verify the installation](/docs/setup/install/kubestash/configuration/) steps. +Once all three Applications are healthy, follow the [Common Configuration](/docs/setup/install/kubestash/configuration/) steps to verify the installation. diff --git a/docs/setup/install/kubestash/fluxcd.md b/docs/setup/install/kubestash/fluxcd.md index 36009be..4f503ca 100644 --- a/docs/setup/install/kubestash/fluxcd.md +++ b/docs/setup/install/kubestash/fluxcd.md @@ -138,4 +138,4 @@ Notes: - `ace-user-roles.enabled: false` is set on the KubeStash HelmRelease because the `ace-user-roles` chart is already managed by its own HelmRelease (step 2). - FluxCD's `helm-controller` reconciles by re-running `helm upgrade`, so unlike ArgoCD you do not need to declare `ignoreDifferences` for the operator's rotating TLS certs and webhook CA bundles. -Once all three HelmReleases report `Ready`, follow the [verify the installation](/docs/setup/install/kubestash/configuration/) steps. +Once all three HelmReleases report `Ready`, follow the [Common Configuration](/docs/setup/install/kubestash/configuration/) steps to verify the installation. diff --git a/docs/setup/install/kubestash/openshift.md b/docs/setup/install/kubestash/openshift.md index 074f0ad..e3f1477 100644 --- a/docs/setup/install/kubestash/openshift.md +++ b/docs/setup/install/kubestash/openshift.md @@ -18,7 +18,7 @@ There are two ways to deploy KubeStash in [OpenShift](https://www.redhat.com/en/ ### Option A: Standard chart with OpenShift values -Use the same `kubestash` chart shown above and enable the OpenShift distribution values. This switches the operator to UBI-based images and applies the SecurityContextConstraints and other OpenShift-specific tweaks: +Use the standard [`kubestash` chart](/docs/setup/install/kubestash/helm/) and enable the OpenShift distribution values. This switches the operator to UBI-based images and applies the SecurityContextConstraints and other OpenShift-specific tweaks: ```bash $ helm install kubestash oci://ghcr.io/appscode-charts/kubestash \ @@ -65,4 +65,4 @@ $ helm install kubestash oci://ghcr.io/appscode-charts/kubestash-certified \ --wait --burst-limit=10000 --debug ``` -Once installed, follow the [verify the installation](/docs/setup/install/kubestash/configuration/) steps to confirm the operator and Addon catalogs are running. +Once installed, follow the [Common Configuration](/docs/setup/install/kubestash/configuration/) steps to verify the operator and Addon catalogs are running. diff --git a/docs/setup/install/kubestash/yaml.md b/docs/setup/install/kubestash/yaml.md index 8ab2472..7826cd8 100644 --- a/docs/setup/install/kubestash/yaml.md +++ b/docs/setup/install/kubestash/yaml.md @@ -14,7 +14,7 @@ section_menu_id: setup # 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. +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 procedure using Helm 3. ```bash $ helm template kubestash oci://ghcr.io/appscode-charts/kubestash \ From df4fec14a377bd539e131f9bd4a1c6e71c742d5c Mon Sep 17 00:00:00 2001 From: Anisur Rahman Date: Tue, 16 Jun 2026 12:38:48 +0600 Subject: [PATCH 6/7] Fix broken sibling links in install guides Point the per-method install guide cross-links at the actual .md files so the liche link checker can resolve them locally (the pretty-URL form with a trailing slash has no matching file/directory on disk). Signed-off-by: Anisur Rahman --- docs/setup/install/kubestash/_index.md | 12 ++++++------ docs/setup/install/kubestash/argocd.md | 2 +- docs/setup/install/kubestash/fluxcd.md | 2 +- docs/setup/install/kubestash/helm.md | 2 +- docs/setup/install/kubestash/openshift.md | 4 ++-- docs/setup/install/kubestash/yaml.md | 2 +- 6 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/setup/install/kubestash/_index.md b/docs/setup/install/kubestash/_index.md index b66f06c..8db42ba 100644 --- a/docs/setup/install/kubestash/_index.md +++ b/docs/setup/install/kubestash/_index.md @@ -24,13 +24,13 @@ Download a FREE license from [AppsCode License Server](https://appscode.com/issu KubeStash can be installed in several ways. Pick the one that fits your workflow: -- [Helm 3](/docs/setup/install/kubestash/helm/) — recommended for most users. -- [YAML](/docs/setup/install/kubestash/yaml/) — render manifests and apply with `kubectl`. -- [ArgoCD](/docs/setup/install/kubestash/argocd/) — GitOps via ArgoCD `Application` resources. -- [FluxCD](/docs/setup/install/kubestash/fluxcd/) — GitOps via the Flux Helm Controller. -- [OpenShift](/docs/setup/install/kubestash/openshift/) — standard chart or Red Hat certified chart. +- [Helm 3](/docs/setup/install/kubestash/helm.md) — recommended for most users. +- [YAML](/docs/setup/install/kubestash/yaml.md) — render manifests and apply with `kubectl`. +- [ArgoCD](/docs/setup/install/kubestash/argocd.md) — GitOps via ArgoCD `Application` resources. +- [FluxCD](/docs/setup/install/kubestash/fluxcd.md) — GitOps via the Flux Helm Controller. +- [OpenShift](/docs/setup/install/kubestash/openshift.md) — standard chart or Red Hat certified chart. -After installing, see [Common Configuration](/docs/setup/install/kubestash/configuration/) to verify the installation. +After installing, see [Common Configuration](/docs/setup/install/kubestash/configuration.md) to verify the installation. ## Purchase KubeStash License diff --git a/docs/setup/install/kubestash/argocd.md b/docs/setup/install/kubestash/argocd.md index f45c563..d980c80 100644 --- a/docs/setup/install/kubestash/argocd.md +++ b/docs/setup/install/kubestash/argocd.md @@ -184,4 +184,4 @@ Notes: - `ace-user-roles.enabled: false` is set on the KubeStash Application because the `ace-user-roles` chart is already managed by its own Application (step 1). - The `ignoreDifferences` entries cover the webhook CA bundles, operator TLS secret and the reload annotation that KubeStash flips when its configuration changes. Without them ArgoCD would report the Application as out-of-sync after every reconciliation. -Once all three Applications are healthy, follow the [Common Configuration](/docs/setup/install/kubestash/configuration/) steps to verify the installation. +Once all three Applications are healthy, follow the [Common Configuration](/docs/setup/install/kubestash/configuration.md) steps to verify the installation. diff --git a/docs/setup/install/kubestash/fluxcd.md b/docs/setup/install/kubestash/fluxcd.md index 4f503ca..761fcfb 100644 --- a/docs/setup/install/kubestash/fluxcd.md +++ b/docs/setup/install/kubestash/fluxcd.md @@ -138,4 +138,4 @@ Notes: - `ace-user-roles.enabled: false` is set on the KubeStash HelmRelease because the `ace-user-roles` chart is already managed by its own HelmRelease (step 2). - FluxCD's `helm-controller` reconciles by re-running `helm upgrade`, so unlike ArgoCD you do not need to declare `ignoreDifferences` for the operator's rotating TLS certs and webhook CA bundles. -Once all three HelmReleases report `Ready`, follow the [Common Configuration](/docs/setup/install/kubestash/configuration/) steps to verify the installation. +Once all three HelmReleases report `Ready`, follow the [Common Configuration](/docs/setup/install/kubestash/configuration.md) steps to verify the installation. diff --git a/docs/setup/install/kubestash/helm.md b/docs/setup/install/kubestash/helm.md index fbc65a2..cf7364b 100644 --- a/docs/setup/install/kubestash/helm.md +++ b/docs/setup/install/kubestash/helm.md @@ -26,4 +26,4 @@ $ helm install kubestash oci://ghcr.io/appscode-charts/kubestash \ To see the detailed configuration options, visit [here](https://github.com/kubestash/installer/tree/master/charts/kubestash). -Next: [verify the installation](/docs/setup/install/kubestash/configuration/). +Next: [verify the installation](/docs/setup/install/kubestash/configuration.md). diff --git a/docs/setup/install/kubestash/openshift.md b/docs/setup/install/kubestash/openshift.md index e3f1477..3fe803e 100644 --- a/docs/setup/install/kubestash/openshift.md +++ b/docs/setup/install/kubestash/openshift.md @@ -18,7 +18,7 @@ There are two ways to deploy KubeStash in [OpenShift](https://www.redhat.com/en/ ### Option A: Standard chart with OpenShift values -Use the standard [`kubestash` chart](/docs/setup/install/kubestash/helm/) and enable the OpenShift distribution values. This switches the operator to UBI-based images and applies the SecurityContextConstraints and other OpenShift-specific tweaks: +Use the standard [`kubestash` chart](/docs/setup/install/kubestash/helm.md) and enable the OpenShift distribution values. This switches the operator to UBI-based images and applies the SecurityContextConstraints and other OpenShift-specific tweaks: ```bash $ helm install kubestash oci://ghcr.io/appscode-charts/kubestash \ @@ -65,4 +65,4 @@ $ helm install kubestash oci://ghcr.io/appscode-charts/kubestash-certified \ --wait --burst-limit=10000 --debug ``` -Once installed, follow the [Common Configuration](/docs/setup/install/kubestash/configuration/) steps to verify the operator and Addon catalogs are running. +Once installed, follow the [Common Configuration](/docs/setup/install/kubestash/configuration.md) steps to verify the operator and Addon catalogs are running. diff --git a/docs/setup/install/kubestash/yaml.md b/docs/setup/install/kubestash/yaml.md index 7826cd8..a282ffd 100644 --- a/docs/setup/install/kubestash/yaml.md +++ b/docs/setup/install/kubestash/yaml.md @@ -25,4 +25,4 @@ $ helm template kubestash oci://ghcr.io/appscode-charts/kubestash \ To see the detailed configuration options, visit [here](https://github.com/kubestash/installer/tree/master/charts/kubestash). -Next: [verify the installation](/docs/setup/install/kubestash/configuration/). +Next: [verify the installation](/docs/setup/install/kubestash/configuration.md). From 5de2a72831aa65eb482438863cc0bd6af4d18d12 Mon Sep 17 00:00:00 2001 From: Anisur Rahman Date: Tue, 16 Jun 2026 13:19:07 +0600 Subject: [PATCH 7/7] Resolve review changes Signed-off-by: Anisur Rahman --- docs/setup/install/kubestash/configuration.md | 12 +++++++----- docs/setup/install/kubestash/fluxcd.md | 2 ++ 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/setup/install/kubestash/configuration.md b/docs/setup/install/kubestash/configuration.md index eb399bb..3bc22b4 100644 --- a/docs/setup/install/kubestash/configuration.md +++ b/docs/setup/install/kubestash/configuration.md @@ -18,15 +18,16 @@ The steps below apply regardless of which [installation method](/docs/setup/inst ## Verify installation -To check if KubeStash operator pods have started, run the following command: +To check if KubeStash operator and webhook 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 -stash kubestash-kubestash-operator-fcd8bf7c6-psjs6 2/2 Running 0 5m49s +$ kubectl get pods -n stash -l app.kubernetes.io/instance=kubestash --watch +NAME READY STATUS RESTARTS AGE +kubestash-kubestash-operator-fcd8bf7c6-psjs6 2/2 Running 0 5m49s +kubestash-kubestash-operator-webhook-server-6fb8f5cfb9-scrx8 1/1 Running 0 5m49s ``` -Once the operator pod is running, you can cancel the above command by typing `Ctrl+C`. +Once the operator and webhook pods are 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 @@ -55,6 +56,7 @@ $ kubectl get addons.addons.kubestash.com NAME AGE kubedump-addon 7m1s pvc-addon 7m1s +vault-addon 7m1s workload-addon 7m1s ``` diff --git a/docs/setup/install/kubestash/fluxcd.md b/docs/setup/install/kubestash/fluxcd.md index 761fcfb..d85112f 100644 --- a/docs/setup/install/kubestash/fluxcd.md +++ b/docs/setup/install/kubestash/fluxcd.md @@ -106,6 +106,8 @@ spec: token: '****************************************' ``` +> **Note:** You can find the latest `license-proxyserver` chart version from the [chart repository](https://github.com/appscode-cloud/installer/tree/master/charts/license-proxyserver) and set it under the `spec.chart.spec.version` field above. + ### 4. Install KubeStash ```yaml