Merge pull request #85 from zackbradys/main

updated/cleaned up `carbide-docs` to support `hauler`
rancherfederal · Feb 13, 2024 · 3215f4a · 3215f4a
2 parents 2f8af15 + 63dcfc4
commit 3215f4a
Show file tree

Hide file tree

Showing 46 changed files with 2,433 additions and 10,892 deletions.
diff --git a/Makefile b/Makefile
@@ -1,12 +1,37 @@
+# makefile for carbide-docs
+
+# set the port
 PORT:= 3000
 
+# docker build for carbide docs
 build:
 	docker rm --force carbide-docs; docker build -t carbide-docs -f Dockerfile.local .
-run: 
+
+# docker run for carbide-docs
+run:
 	docker run -p ${PORT}:3000 --name=carbide-docs -ti carbide-docs; docker logs -f carbide-docs
 
-local:
-	npm start
+# run all build commands
+local-all: local-install local-build local-serve
+
+# install dependencies
+local-install:
+	npm install
 
+# test and run carbide-docs
+# opens localhost:3000/carbide-docs
+local-test:
+	npm run start
+
+# build and compile carbide-docs
 local-build:
 	npm run build
+
+# server carbide-docs from build
+# opens localhost:5000/carbide-docs
+local-serve:
+	npm run serve
+
+# clear build outputs
+clear:
+	npm run clear && rm -rf node_modules
diff --git a/blog/2019-05-28-first-blog-post.md b/blog/2019-05-28-first-blog-post.md
diff --git a/blog/2019-05-29-long-blog-post.md b/blog/2019-05-29-long-blog-post.md
diff --git a/blog/2021-08-01-mdx-blog-post.mdx b/blog/2021-08-01-mdx-blog-post.mdx
diff --git a/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg b/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg
diff --git a/blog/2021-08-26-welcome/index.md b/blog/2021-08-26-welcome/index.md
diff --git a/blog/authors.yml b/blog/authors.yml
diff --git a/docs/airgapped-docs/getting-started.md b/docs/airgapped-docs/getting-started.md
@@ -0,0 +1,64 @@
+# Getting Started
+
+This will guide you through getting started with Airgapped Docs.
+
+## Airgapped Docs Images
+
+The images for Airgapped Docs can be found [here](https://github.com/rancherfederal/carbide-releases/releases). You'll need to pull these images using `hauler`.
+
+### Internet-Connected Environment
+
+If you're working in a connected environment, look [here](../registry-docs/copying-images.md) for instructions on pulling the images into your registry.
+
+### Airgapped Environment
+
+If you're working in an airgapped environment, look [here](../registry-docs/downloading-images.md) for instructions on pulling the images locally.
+
+On the airgap, look [here](../registry-docs/loading-images.md) for loading the localized images into the airgapped registry.
+
+## Airgapped Docs Helm Chart
+
+The chart for Airgapped Docs can be found [here](../carbide-charts.md). You'll need to pull the chart using `hauler`.
+
+## Configuring Registry Credentials
+
+### Local Cluster
+
+On the local cluster running Rancher Multi-cluster Manager, you'll need to configure credentials for the registry with the Airgapped Docs images. See the [Rancher Configuration](../registry-docs/rancher-config.md) on how to set up those credentials.
+
+### Downstream Clusters
+
+For downstream clusters, you'll need to also configure registry credentials. Depending on how RKE2 was configured and set up, there are a few ways to do this.
+
+### Rancher-Provisioned Cluster
+
+If you provisioned or are provisioning RKE2 directly from the Rancher UI, you can configure/update that cluster with credentials.
+
+1. Click the upper-left menu and navigate to `Cluster Management`.
+2. If updating an existing cluster, select that cluster, click the 3-dot menu in the upper-right, and select `Edit Config`. If creating a new cluster, just click `Create` in the upper-left.
+3. Once you get to the screen to update/create the cluster's node pools, scroll to the bottom under `Cluster Configuration` and find the `Registries` tab.
+4. Select the second option (`Use specified private registry for Rancher System Container Images`).
+5. Enter your registry hostname in the first box.
+6. In the `Authentication` box, select `Create a HTTP Basic Auth Secret` and enter your credentials.
+
+- For future clusters using the same registry, you can just select existing secret.
+
+7. Click `Save`.
+
+![Rancher Registry Configuration](/img/registry-configuration.png)
+
+8. Wait for cluster to reconcile.
+
+### Imported Cluster
+
+If you're working with a cluster that was imported or is to be imported into the Rancher MCM, you'll need to update the containerd `registries.yaml` file on every node, substituting your registry hostname and credentials:
+
+```bash
+# /etc/rancher/k3s/registries.yaml
+# /etc/rancher/rke2/registries.yaml
+configs:
+  "YOUR_REGISTRY_HOSTNAME":
+    auth:
+      username: YOUR_REGISTRY_USERNAME
+      password: YOUR_REGISTRY_PASSWORD
+```
diff --git a/docs/airgapped-docs/installation.md b/docs/airgapped-docs/installation.md
@@ -1,14 +1,12 @@
 # Installation
 
-## Downstream RKE2 Clusters
+## Downstream Clusters
 
-On downstream RKE2 clusters, you'll need to first install Rancher's CIS Benchmark Operator:
-
-1. Run the following Helm command to install Airgapped Docs chart, substituting your registry in:
+Run the following Helm command to install Airgapped Docs chart, substituting your registry in:
 
 ```bash
 helm install -n carbide-docs-system --create-namespace \
-    --set "global.cattle.systemDefaultRegistry=YOUR_REGISTRY_HERE" \
+    --set "global.cattle.systemDefaultRegistry=<registry-url>" \
     airgapped-docs carbide-charts/airgapped-docs
 ```
 
@@ -27,7 +25,7 @@ There may be situations where you are running in a low-compute, low-resource env
 ```bash
 # Disable neuvector docs
 helm install -n carbide-docs-system --create-namespace \
-  --set "global.cattle.systemDefaultRegistry=YOUR_REGISTRY_HERE" \
+  --set "global.cattle.systemDefaultRegistry=<registry-url>" \
   --set "docs.neuvector.enabled=false" \
   airgapped-docs carbide-charts/airgapped-docs
 ```

diff --git a/docs/airgapped-docs/introduction.md b/docs/airgapped-docs/introduction.md
@@ -1,15 +1,17 @@
 # Introduction
 
-This page will walk through Installation and Usage of the Airgapped Docs component of RGS Carbide.
+This page will walk through installation and usage of the Airgapped Docs component of Rancher Government Carbide.
 
 ## IOC Expectations
+
 As our product is still at Initial Operation Capability (IOC), there are some expectations to level-set:
 
-* Installation and packaging is still in progress and improving.
+- Installation and packaging is still in progress and improving.
 
-If you see issues and areas for improvement, please submit Github issues [here](https://github.com/rancherfederal/ssf-feedback/issues/).
+If you see issues and areas for improvement, please submit Github issues [here](https://github.com/rancherfederal/carbide-charts/issues/).
 
 ## What is this?
+
 When in an airgap, having accessibility to documentation can be critical to mission success, especially while troubleshooting problems.
 
 Carbide Airgapped Docs will give Rancher supported users access to documentation for not only Carbide itself, but the entire supported Rancher product porfolio. This includes capabililites like query and copy/paste shortcuts.
diff --git a/docs/airgapped-docs/prereqs.md b/docs/airgapped-docs/prereqs.md
@@ -1,7 +1,9 @@
 # Prerequisites
 
-In order to install STIGATRON, you need the following:
+In order to utilize Airgapped Docs, you will need the following prerequisites:
 
-* For pulling/storing the STIGATRON images in your registry, you'll need the [Cosign CLI](https://github.com/sigstore/cosign).
-* For installation, you'll need the [Helm CLI](https://helm.sh/docs/intro/install/).
-* From the Rancher Manager UI, access to the downstream RKE2 cluster(s) you want to install Airgapped Docs onto.
+- **Rancher v2.7.0 or higher:** https://ranchermanager.docs.rancher.com/integrations-in-rancher/rancher-extensions
+- For fetching and packaging... **Hauler:** https://github.com/rancherfederal/hauler
+- For installation and deployment... **Helm:** https://helm.sh/docs/intro/install
+- Access to the `local` cluster, to be able to install and deploy the app(s).
+- Access to the `downstream` cluster(s), to be able to install and deploy the app(s).
diff --git a/docs/airgapped-docs/uninstall.md b/docs/airgapped-docs/uninstall.md
@@ -1,8 +1,8 @@
 # Uninstall
 
-## Downstream RKE2 Clusters
+## Downstream Clusters
 
-On each downstream RKE2 cluster, run the following command to uninstall Airgapped Docs:
+On each downstream cluster, run the following command to uninstall Airgapped Docs:
 
 ```bash
 helm uninstall -n carbide-docs-system airgapped-docs

diff --git a/docs/carbide-charts.md b/docs/carbide-charts.md
@@ -0,0 +1,82 @@
+# Carbide Helm Charts
+
+### Available Helm Charts
+
+```bash
+NAME                            CHART VERSION   APP VERSION     DESCRIPTION
+carbide-charts/airgapped-docs   0.1.47          0.1.2           Rancher Government Airgapped Docs
+carbide-charts/heimdall2        0.1.45          0.1.1           Rancher Government Heimdall2 Tool
+carbide-charts/rancher          2.8.2           v2.8.2          Install Rancher Server to manage Kubernetes...
+carbide-charts/stigatron        0.2.5           0.2.2           Rancher Government Stigatron Extension
+carbide-charts/stigatron-ui     0.2.3           0.2.0           Rancher Government Stigatron UI Extension
+```
+
+## How To Use (Connected Environments)
+
+### For Helm Chart Repositories
+
+```bash
+# add and update the helm chart repository
+helm repo add carbide-charts https://rancherfederal.github.io/carbide-charts
+helm repo update
+
+# view the charts in the helm chart repository
+helm search repo carbide-charts
+
+# example install of a helm chart
+helm install <release-name> carbide-charts/<chart>
+```
+
+If you would like to do add the Carbide Helm Charts to the Rancher Manager Chart Catalog, so you are able to use the user interface to install them, please follow the steps in the [Rancher Manager Docs](https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/helm-charts-in-rancher).
+
+## How to Use (Airgaped Environments)
+
+### For Helm Chart Repositories
+
+#### On Connected Environment
+
+```bash
+# generate the hauler manfiest for the carbide charts
+cat <<EOF > carbide-charts.yaml
+apiVersion: content.hauler.cattle.io/v1alpha1
+kind: Charts
+metadata:
+  name: carbide-charts
+spec:
+  charts:
+    - name: airgapped-docs
+      repoURL: https://rancherfederal.github.io/carbide-charts
+      version: 0.1.47
+    - name: heimdall2
+      repoURL: https://rancherfederal.github.io/carbide-charts
+      version: 0.1.45
+    - name: rancher
+      repoURL: https://rancherfederal.github.io/carbide-charts
+      version: 2.8.2
+    - name: stigatron
+      repoURL: https://rancherfederal.github.io/carbide-charts
+      version: 0.2.5
+    - name: stigatron-ui
+      repoURL: https://rancherfederal.github.io/carbide-charts
+      version: 0.2.3
+EOF
+
+# fetch the content from generated hauler manifest
+hauler store sync -f carbide-charts.yaml
+
+# save and output the content from the hauler store to tarball
+hauler store save --filename carbide-charts.tar.zst
+```
+
+#### On Airgapped Environment
+
+```bash
+# load the content from the tarball to the hauler store
+hauler store load carbide-charts.tar.zst
+
+# server the content from the hauler store
+hauler store serve fileserver
+
+# example install of a helm chart
+helm install <release-name> http://<FQDN or IP>:<PORT>/<chart>.tgz
+```
diff --git a/docs/feedback.md b/docs/feedback.md
@@ -0,0 +1,5 @@
+# Feedback
+
+Feedback is **critical** to us to continue to improve our tools and help you with your mission.
+
+For any issues, concerns, or questions, please open an issue: https://github.com/rancherfederal/carbide-docs/issues