Merge pull request #96 from rancherfederal/docs_refactor

Docs refactor
rancherfederal · Jun 28, 2024 · b67a80b · b67a80b
2 parents 197e1d9 + 8b8b26b
commit b67a80b
Show file tree

Hide file tree

Showing 17 changed files with 191 additions and 405 deletions.
diff --git a/docs/airgapped-docs/getting-started.md b/docs/airgapped-docs/getting-started.md
diff --git a/docs/airgapped-docs/prereqs.md b/docs/airgapped-docs/prereqs.md
@@ -3,7 +3,14 @@
 In order to utilize Airgapped Docs, you will need the following prerequisites:
 
 - **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).
+- **Helm:** https://helm.sh/docs/intro/install
+- Access to the `downstream` cluster(s), to be able to install and deploy the app(s).
+
+It is also assumed you have followed all of the Carbide Secured Registry (CSR) documentation.
+
+This means you have:
+- seeded your registry with the images from the CSR
+- the carbide helm charts available for use
+- configured k3s/rke2 to use your registry
+- configured Rancher Manager to use your registry
+- setup policy enforcement to only allow images from the CSR
diff --git a/docs/carbide-charts.md → docs/registry-docs/carbide-charts.md b/docs/carbide-charts.md → docs/registry-docs/carbide-charts.md
@@ -1,7 +1,8 @@
 # Carbide Helm Charts
 
-### Available Helm Charts
+Along with the our secured images provided through the CSR, we also provide helm charts to install various components of the carbide product suite. These include charts include the necessary components to run STIGATRON, an airgapped copy of all rancher product docs, as well as custom build of rancher with our white-labeling.
 
+**Available Helm Charts**
 ```bash
 NAME                            CHART VERSION   APP VERSION     DESCRIPTION
 carbide-charts/airgapped-docs   0.1.49          0.1.4           Rancher Government Airgapped Docs
@@ -11,10 +12,11 @@ carbide-charts/stigatron        0.2.5           0.2.2           Rancher Governme
 carbide-charts/stigatron-ui     0.2.3           0.2.0           Rancher Government Stigatron UI Extension
 ```
 
-## How To Use (Connected Environments)
+The charts are available at https://rancherfederal.github.io/carbide-charts.
 
-### For Helm Chart Repositories
+## Obtaining Chart Manifests
 
+### Connected Environments
 ```bash
 # add and update the helm chart repository
 helm repo add carbide-charts https://rancherfederal.github.io/carbide-charts
@@ -27,14 +29,11 @@ helm search repo carbide-charts
 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).
+If you would like to add the Carbide Helm Charts to the Rancher Manager Chart Catalog (so you can 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
+### Airgapped Environments
 
+#### In Connected Environment
 ```bash
 # generate the hauler manfiest for the carbide charts
 cat <<EOF > carbide-charts.yaml
@@ -79,8 +78,7 @@ hauler store sync --store carbide-store --files carbide-charts.yaml --platform <
 hauler store save --store carbide-store --filename carbide-charts.tar.zst
 ```
 
-#### On Airgapped Environment
-
+#### In Airgapped Environment
 ```bash
 # load the content from the tarball to the hauler store
 hauler store load --store carbide-store carbide-charts.tar.zst

diff --git a/docs/registry-docs/kubernetes-config.md → ...registry-docs/configuration/kubernetes.md b/docs/registry-docs/kubernetes-config.md → ...registry-docs/configuration/kubernetes.md
@@ -10,6 +10,11 @@ The full configuration using your authenticated registry is below:
 
 ```yaml
 # /etc/rancher/k3s/registries.yaml
+mirrors:
+  docker.io:
+      endpoint:
+      - "https://<registry-url>"
+
 configs:
   "<registry-url>":
     auth:
@@ -31,6 +36,11 @@ The full configuration using the shared alpha account is below:
 
 ```yaml
 # /etc/rancher/rke2/registries.yaml
+mirrors:
+  docker.io:
+      endpoint:
+      - "https://<registry-url>"
+
 configs:
   "<registry-url>":
     auth:
@@ -47,3 +57,34 @@ write-kubeconfig-mode: 0640
 system-default-registry: <registry-url>
 ...
 ```
+
+#### `registries.yaml` Strategy Approaches
+
+| Scenario                    | Best practice                                                            |
+| --------------------------- | ------------------------------------------------------------------------ |
+| Use of a 'golden machine image'     | Pre-configure `registries.yaml` on golden machine image before host provisioning |
+| Rancher provisioned cluster | Embed a `cloud-init` file into cluster provisioning (Example below)      |
+| Ansible/Saltstack/Manual    | Pre-configure `registries.yaml` on host before cluster provisioning      |
+
+#### Example `cloud-init` (`RKE2`)
+
+```yaml
+# cloud-init
+
+runcmd:
+  - mkdir /etc/rancher/rke2
+write_files:
+  - path: /etc/rancher/rke2/registries.yaml
+    content: |
+      mirrors:
+        docker.io:
+            endpoint:
+            - "https://<registry-url>"
+
+        configs:
+        "<registry-url>":
+            auth:
+            username: <redacted>
+            password: <redacted>
+    permissions: '0644'
+```
diff --git a/docs/registry-docs/rancher-config.md → docs/registry-docs/configuration/rancher.md b/docs/registry-docs/rancher-config.md → docs/registry-docs/configuration/rancher.md
@@ -1,8 +1,8 @@
 # Rancher Manager Configuration
 
-This page will walk you through how to configure Rancher Manager images instead of the upstream Docker hub images, both for its own components and downstream Rancher Kubernetes clusters (RKE2/K3s).
+This page will walk you through how to configure Rancher Manager to use images from the CSR instead of the upstream Docker Hub images. This will apply to both its own components and downstream Rancher Kubernetes clusters (RKE2/K3s).
 
-**NOTE**: Due to current limitations of cloud providers, this project will not work for managing Cloud Provider clusters (AKS, EKS, GKE). If you're currently using Rancher to manage those workloads, do not use this project. We intend to improve this experience in the future.
+> **NOTE**: Due to current limitations of cloud providers, this project will not work for managing Cloud Provider clusters (AKS, EKS, GKE). If you're currently using Rancher to manage those workloads, do not use this project. We intend to improve this experience in the future.
 
 ## Compatibility Matrix
 
@@ -14,22 +14,22 @@ This page will walk you through how to configure Rancher Manager images instead
 | Any     | Imported Cluster             | Unknown                                         |             |
 | AWS-EKS | Rancher                      | ECR (public or private)                         |             |
 
-## Configuring Cert Manager
+### Preliminary Setup
 
-As Rancher has a dependency on Cert Manager, you'll need to update your Helm install of Cert Manager to use Carbide Secured Registry (CSR) images that are validated and signed by Rancher Government.
+As Rancher has a dependency on Cert Manager, you'll need to update/install Cert Manager with the images provided by the CSR.
 
 If you're following Rancher's [Connected](https://rancher.com/docs/rancher/v2.6/en/installation/install-rancher-on-k8s/#4-install-cert-manager) installation instructions, you'll need to follow the next steps to use the Carbide Secured Registry (CSR) images for cert-manager.
 
 If using the [Airgapped](https://rancher.com/docs/rancher/v2.6/en/installation/other-installation-methods/air-gap/install-rancher/#1-add-the-cert-manager-repo) installation instructions, make sure you've pulled the images to your local/airgapped registry.
 
-### Cert Manager Helm Install
+#### Configuring Cert Manager
 
 Follow Rancher's [Connected](https://rancher.com/docs/rancher/v2.6/en/installation/install-rancher-on-k8s/#4-install-cert-manager) installation instructions, but using the following steps instead of the `helm install` command from the docs.
 
 After adding the Cert Manager repo and installing the CRDs, use the following to create a temporary `values.yaml` for your chart, subsituting your registry domain:
 
 ```
-cat <<EOT > /tmp/cert-manager-values.yaml
+cat <<EOT > /tmp/values.yaml
 image:
   registry: <registry-url>
   repository: jetstack/cert-manager-controller
@@ -66,11 +66,13 @@ helm install cert-manager jetstack/cert-manager \
   -f /tmp/values.yaml
 ```
 
-## Registry Auth Scenarios
+## Registry Auth Strategies
 
-### Global Registry
+### Global Registry (Rancher)
 
-#### Setting a Private Registry with No Credentials as the Default Registry
+#### Existing Rancher Installations
+
+##### Setting a Private Registry with No Credentials as the Default Registry
 
 1. Log into Rancher and configure the default administrator password.
 1. Click **☰ > Global Settings**.
@@ -79,7 +81,7 @@ helm install cert-manager jetstack/cert-manager \
 
 **Result:** Rancher will use your private registry to pull system images.
 
-#### Setting a Private Registry with Credentials when Deploying a Cluster
+##### Setting a Private Registry with Credentials when Deploying a Cluster
 
 You can follow these steps to configure a private registry when you create a cluster:
 
@@ -92,46 +94,13 @@ You can follow these steps to configure a private registry when you create a clu
 
 **Result:** The new cluster will be able to pull images from the private registry.
 
-### Manual `registries.yaml` configuration (`RKE2`/`k3s`)
-
-In order to configure authentication to the CRI _before_ pulling down the base kubernetes container image. To modify the system images that `k3s` or `rke2` uses upon bootstrapping, configure k3s' mirror settings as described [here](https://rancher.com/docs/k3s/latest/en/installation/private-registry/#mirrors).
-
-The full configuration using the shared alpha account is below:
-
-```yaml
-# /etc/rancher/k3s/registries.yaml
-# /etc/rancher/rke2/registries.yaml
-mirrors:
-  docker.io:
-    endpoint:
-      - "https://<registry-url>"
-
-configs:
-  "<registry-url>":
-    auth:
-      username: <redacted>
-      password: <redacted>
-```
-
-#### `registries.yaml` Strategy
+#### New Rancher Installations
 
-| Scenario                    | Best practice                                                            |
-| --------------------------- | ------------------------------------------------------------------------ |
-| Use of a 'golden image'     | Pre-configure `registries.yaml` on golden image before host provisioning |
-| Rancher provisioned cluster | Embed a `cloud-init` file into cluster provisioning (Example below)      |
-| Ansible/Saltstack/Manual    | Pre-configure `registries.yaml` on host before cluster provisioning      |
+Follow Rancher's [Installation Guide](https://rancher.com/docs/rancher/v2.5/en/installation/install-rancher-on-k8s), making sure to use the carbide chart obtained in the previous [helm chart](../carbide-charts.md) section.
 
-### Usage with `Rancher`
-
-Follow Rancher's [Installation Guide](https://rancher.com/docs/rancher/v2.5/en/installation/install-rancher-on-k8s), adding in the following steps to use our [Carbide Helm Chart](https://github.com/rancherfederal/carbide-charts) and the `helm install` command.
-
-When installing Rancher, to utilize the private registry, you'll need to set the following values in your Helm values:
+When installing Rancher, to utilize the private registry, you'll need to set the following values in your helm values:
 
 ```bash
-helm repo add carbide-charts https://rancherfederal.github.io/carbide-charts
-helm repo update
-helm search repo carbide-charts
-
 helm install rancher carbide-charts/rancher \
   --namespace cattle-system \
   --set hostname=rancher.my.org \
@@ -140,27 +109,8 @@ helm install rancher carbide-charts/rancher \
   --set systemDefaultRegistry=<registry-url>
 ```
 
-**NOTE:** This requires configuring your above K3s/RKE2 `registries.yaml` to work.
-
-#### Example `cloud-init` (`RKE2`)
-
-```yaml
-# cloud-init
-
-runcmd:
-  - mkdir /etc/rancher/rke2
-write_files:
-  - path: /etc/rancher/rke2/registries.yaml
-    content: |
-      mirrors:
-        docker.io:
-            endpoint:
-            - "https://<registry-url>"
-
-        configs:
-        "<registry-url>":
-            auth:
-            username: <redacted>
-            password: <redacted>
-    permissions: '0644'
-```
+> **NOTE:** This requires configuring RKE2/K3s `registries.yaml` to work. See the [RKE2/K3s configuration](../configuration/kubernetes.md) section for more details.
+
+###  Authenticated Registry (Manual registries.yaml)
+
+See the [RKE2/K3s configuration](../configuration/kubernetes.md) section for more details.