From 6148154159bac1208d713de8cf521e8668b0898d Mon Sep 17 00:00:00 2001 From: clayton Date: Thu, 20 Jun 2024 18:30:43 -0700 Subject: [PATCH 01/13] move cosign v2 explanation to top level for better clarity --- docs/registry-docs/validating-images.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/registry-docs/validating-images.md b/docs/registry-docs/validating-images.md index 2f28a2b..f0b3cdd 100644 --- a/docs/registry-docs/validating-images.md +++ b/docs/registry-docs/validating-images.md @@ -23,13 +23,13 @@ Before pulling images or even after images have been pushed to a registry, you s **NOTE:** You'll need to substitute `rgcrprod.azurecr.us` with your own registry domain, if verifying images in your own registry. -
-Carbide Images v2 (Starting 03/2024) - In Carbide Images v2 (or Cosign v2), the attachment of supply chain artifacts to the top layer of an image has been deprecated. In order for us to maintain interoperability, we have migrated our images and supply chain artifacts to be attached at the individual layer for a specific platform or architecture of an image. If you would like to see more information, please see the noticed posted [here](https://github.com/sigstore/cosign/blob/main/specs/SBOM_SPEC.md)! +
+Carbide Images v2 (After 03/2024) + ## Display Supply Chain Artifacts ```bash From 2d0c64a05bd0430a61e4c0b6bcb83bb46e58be65 Mon Sep 17 00:00:00 2001 From: clayton Date: Thu, 20 Jun 2024 19:22:41 -0700 Subject: [PATCH 02/13] rearrange/refactor registry documentation - remove duplicate instructions - add clearer descriptions --- docs/registry-docs/copying-images.md | 74 ++++++------------------ docs/registry-docs/downloading-images.md | 74 ++++++------------------ sidebars.js | 27 +++++---- 3 files changed, 53 insertions(+), 122 deletions(-) diff --git a/docs/registry-docs/copying-images.md b/docs/registry-docs/copying-images.md index 7323673..e5df0a3 100644 --- a/docs/registry-docs/copying-images.md +++ b/docs/registry-docs/copying-images.md @@ -1,12 +1,10 @@ # Copying Images to a Registry -This page will walk you through how you can copy the secured images from the hardened registry into another registry within a connected environment. +This page will walk you through copying our secured images into your own registry for later use. -If you're copying images into an airgap, check the documents [here](downloading-images.md). +If you're hauling images into an airgapped registry, check the documentation [here](downloading-images.md). -## Carbide - -**NOTE:** We are actively working to improve the collection and formatting of the below procceses. Additionally, please see the [Hauler Docs](https://rancherfederal.github.io/hauler-docs/docs/guides-references/hauler-content/images) for how to specify a specific platform. +## Setup ```bash # authenticate into carbide secured registry @@ -14,7 +12,14 @@ hauler login -u -p rgcrprod.azurecr.us # download the public key for carbide curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub +``` + +## Copying Secured Images +**NOTE:** We are actively working to improve the collection and formatting of the below procceses. Additionally, please see the [Hauler Docs](https://rancherfederal.github.io/hauler-docs/docs/guides-references/hauler-content/images) for how to specify a specific platform. +### Carbide + +```bash # generate the hauler manifest for carbide cat < carbide-images.yaml apiVersion: content.hauler.cattle.io/v1alpha1 @@ -45,15 +50,9 @@ hauler store sync --store carbide-store --files carbide-images.yaml --platform < hauler store copy --store carbide-store --username --password registry:// ``` -## K3s +### K3s ```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us - -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub - # fetch the content from the carbide secured registry # verify the version, location of the key, and the platform/architecture hauler store sync --store k3s-store --products k3s=v1.27.12-k3s1 --key carbide-key.pub --platform @@ -62,15 +61,9 @@ hauler store sync --store k3s-store --products k3s=v1.27.12-k3s1 --key carbide-k hauler store copy --store k3s-store --username --password registry:// ``` -## RKE2 +### RKE2 ```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us - -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub - # fetch the content from the carbide secured registry # verify the version, location of the key, and the platform/architecture hauler store sync --store rke2-store --products rke2=v1.27.12+rke2r1 --key carbide-key.pub --platform @@ -78,18 +71,11 @@ hauler store sync --store rke2-store --products rke2=v1.27.12+rke2r1 --key carbi # copy the content from the hauler store to your registry hauler store copy --store rke2-store --username --password registry:// ``` +### Rancher -## Rancher - -### Cert Manager +#### Cert Manager ```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us - -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub - # fetch the content from the carbide secured registry # verify the version, location of the key, and the platform/architecture hauler store sync --store certmanager-store --products cert-manager=v1.14.4 --key carbide-key.pub --platform @@ -98,15 +84,9 @@ hauler store sync --store certmanager-store --products cert-manager=v1.14.4 --ke hauler store copy --store certmanager-store --username --password registry:// ``` -### Rancher +#### Rancher ```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us - -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub - # fetch the content from the carbide secured registry # verify the version, location of the key, and the platform/architecture hauler store sync --store rancher-store --products rancher=v2.8.3 --key carbide-key.pub --platform @@ -115,15 +95,9 @@ hauler store sync --store rancher-store --products rancher=v2.8.3 --key carbide- hauler store copy --store rancher-store --username --password registry:// ``` -## Longhorn +### Longhorn ```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us - -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub - # fetch the content from the carbide secured registry # verify the version, location of the key, and the platform/architecture hauler store sync --store longhorn-store --products longhorn=v1.6.1 --key carbide-key.pub --platform @@ -132,15 +106,9 @@ hauler store sync --store longhorn-store --products longhorn=v1.6.1 --key carbid hauler store copy --store longhorn-store --username --password registry:// ``` -## NeuVector +### NeuVector ```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us - -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub - # fetch the content from the carbide secured registry # verify the version, location of the key, and the platform/architecture hauler store sync --store neuvector-store --products neuvector=v5.3.2 --key carbide-key.pub --platform @@ -149,15 +117,9 @@ hauler store sync --store neuvector-store --products neuvector=v5.3.2 --key carb hauler store copy --store neuvector-store --username --password registry:// ``` -## Kubewarden +### Kubewarden ```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us - -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub - # fetch the content from the carbide secured registry # verify the version, location of the key, and the platform/architecture hauler store sync --store kubewarden-store --products kubewarden=kubewarden-controller-2.0.11 --key carbide-key.pub --platform diff --git a/docs/registry-docs/downloading-images.md b/docs/registry-docs/downloading-images.md index 3a94586..62648f0 100644 --- a/docs/registry-docs/downloading-images.md +++ b/docs/registry-docs/downloading-images.md @@ -1,12 +1,10 @@ # Downloading the Images -This page will walk you through how you can locally download secured images from the hardened registry and package them to move over an airgap to your registry. +This page will walk you through locally downloading our secured images from our hardened registry, as well as packaging them to move over an airgap into your registry. -If you're copying images into a connected registry, check the documents [here](copying-images.md). +If you're hauling images into a connected registry, check the documentation [here](copying-images.md). -## Carbide - -**NOTE:** We are actively working to improve the collection and formatting of the below procceses. Additionally, please see the [Hauler Docs](https://rancherfederal.github.io/hauler-docs/docs/guides-references/hauler-content/images) for how to specify a specific platform. +## Setup ```bash # authenticate into carbide secured registry @@ -14,7 +12,15 @@ hauler login -u -p rgcrprod.azurecr.us # download the public key for carbide curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub +``` + +## Downloading Secured Images + +### Carbide + +**NOTE:** We are actively working to improve the collection and formatting of the below procceses. Additionally, please see the [Hauler Docs](https://rancherfederal.github.io/hauler-docs/docs/guides-references/hauler-content/images) for how to specify a specific platform. +```bash # generate the hauler manifest for carbide cat < carbide-images.yaml apiVersion: content.hauler.cattle.io/v1alpha1 @@ -45,15 +51,9 @@ hauler store sync --store carbide-store --files carbide-images.yaml --platform < hauler store save --store carbide-store --filename carbide-images.tar.zst ``` -## K3s +### K3s ```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us - -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub - # fetch the content from the carbide secured registry # verify the version, location of the key, and the platform/architecture hauler store sync --store k3s-store --products k3s=v1.27.12-k3s1 --key carbide-key.pub --platform @@ -62,15 +62,9 @@ hauler store sync --store k3s-store --products k3s=v1.27.12-k3s1 --key carbide-k hauler store save --store k3s-store --filename k3s-images.tar.zst ``` -## RKE2 +### RKE2 ```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us - -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub - # fetch the content from the carbide secured registry # verify the version, location of the key, and the platform/architecture hauler store sync --store rke2-store --products rke2=v1.27.12+rke2r1 --key carbide-key.pub --platform @@ -79,17 +73,11 @@ hauler store sync --store rke2-store --products rke2=v1.27.12+rke2r1 --key carbi hauler store save --store rke2-store --filename rke2-images.tar.zst ``` -## Rancher +### Rancher -### Cert Manager +#### Cert Manager ```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us - -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub - # fetch the content from the carbide secured registry # verify the version, location of the key, and the platform/architecture hauler store sync --store certmanager-store --products cert-manager=v1.14.4 --key carbide-key.pub --platform @@ -98,15 +86,9 @@ hauler store sync --store certmanager-store --products cert-manager=v1.14.4 --ke hauler store save --store certmanager-store --filename certmanager-images.tar.zst ``` -### Rancher +#### Rancher ```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us - -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub - # fetch the content from the carbide secured registry # verify the version, location of the key, and the platform/architecture hauler store sync --store rancher-store --products rancher=v2.8.3 --key carbide-key.pub --platform @@ -115,15 +97,9 @@ hauler store sync --store rancher-store --products rancher=v2.8.3 --key carbide- hauler store save --store rancher-store --filename rancher-images.tar.zst ``` -## Longhorn +### Longhorn ```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us - -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub - # fetch the content from the carbide secured registry # verify the version, location of the key, and the platform/architecture hauler store sync --store longhorn-store --products longhorn=v1.6.1 --key carbide-key.pub --platform @@ -132,15 +108,9 @@ hauler store sync --store longhorn-store --products longhorn=v1.6.1 --key carbid hauler store save --store longhorn-store --filename longhorn-images.tar.zst ``` -## NeuVector +### NeuVector ```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us - -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub - # fetch the content from the carbide secured registry # verify the version, location of the key, and the platform/architecture hauler store sync --store neuvector-store --products neuvector=v5.3.2 --key carbide-key.pub --platform @@ -149,15 +119,9 @@ hauler store sync --store neuvector-store --products neuvector=v5.3.2 --key carb hauler store save --store neuvector-store --filename neuvector-images.tar.zst ``` -## Kubewarden +### Kubewarden ```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us - -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub - # fetch the content from the carbide secured registry # verify the version, location of the key, and the platform/architecture hauler store sync --store kubewarden-store --products kubewarden=kubewarden-controller-2.0.11 --key carbide-key.pub --platform diff --git a/sidebars.js b/sidebars.js index 80a101a..3ad91bd 100644 --- a/sidebars.js +++ b/sidebars.js @@ -36,18 +36,23 @@ const sidebars = { 'registry-docs/validating-images', { type: 'category', - label: 'Connected Environments', + label: 'Seeding a Registry', items: [ - // 'registry-docs/pulling-images', - 'registry-docs/copying-images', - ], - }, - { - type: 'category', - label: 'Deploying Into Airgaps', - items: [ - 'registry-docs/downloading-images', - 'registry-docs/loading-images', + { + type: 'category', + label: 'Connected Environments', + items: [ + 'registry-docs/copying-images', + ], + }, + { + type: 'category', + label: 'Airgapped Environments', + items: [ + 'registry-docs/downloading-images', + 'registry-docs/loading-images', + ], + }, ], }, ], From eb6b5b280e152aec096214f3e9447601c91f8f7f Mon Sep 17 00:00:00 2001 From: clayton Date: Fri, 21 Jun 2024 16:51:37 -0700 Subject: [PATCH 03/13] refactor registry docs - isolate duplicate setup instructions to prerequisites - lots of minor grammar/formatting changes --- docs/registry-docs/copying-images.md | 10 ------- docs/registry-docs/downloading-images.md | 10 ------- docs/registry-docs/prereqs.md | 38 +++++++++++++++++------- docs/registry-docs/validating-images.md | 15 ---------- 4 files changed, 28 insertions(+), 45 deletions(-) diff --git a/docs/registry-docs/copying-images.md b/docs/registry-docs/copying-images.md index e5df0a3..430c405 100644 --- a/docs/registry-docs/copying-images.md +++ b/docs/registry-docs/copying-images.md @@ -4,16 +4,6 @@ This page will walk you through copying our secured images into your own registr If you're hauling images into an airgapped registry, check the documentation [here](downloading-images.md). -## Setup - -```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us - -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub -``` - ## Copying Secured Images **NOTE:** We are actively working to improve the collection and formatting of the below procceses. Additionally, please see the [Hauler Docs](https://rancherfederal.github.io/hauler-docs/docs/guides-references/hauler-content/images) for how to specify a specific platform. diff --git a/docs/registry-docs/downloading-images.md b/docs/registry-docs/downloading-images.md index 62648f0..d623358 100644 --- a/docs/registry-docs/downloading-images.md +++ b/docs/registry-docs/downloading-images.md @@ -4,16 +4,6 @@ This page will walk you through locally downloading our secured images from our If you're hauling images into a connected registry, check the documentation [here](copying-images.md). -## Setup - -```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us - -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub -``` - ## Downloading Secured Images ### Carbide diff --git a/docs/registry-docs/prereqs.md b/docs/registry-docs/prereqs.md index 234ea21..421c883 100644 --- a/docs/registry-docs/prereqs.md +++ b/docs/registry-docs/prereqs.md @@ -2,14 +2,11 @@ Below are all the things you need to get started with the Hardened Container Registry. As we improve and streamline the process, this list could evolve. -## Registry Disclaimer +>**Registry Disclaimer:** The Carbide Secured Registry (rgcrprod.azurecr.us) is _not_ intended to be used as the primary registry for running Kubernetes clusters. It is only intended as the acquisition point to obtain the Carbide images. Customers should seed their own private registries, and use that registry for their Kubernetes clusters. -The Carbide Secured Registry (rgcrprod.azurecr.us) is _not_ intended to be used as the primary registry for running Kubernetes clusters. It is only intended as the acquisition point to obtain the Carbide images. Customers should seed their own private registries, and use that registry for their Kubernetes clusters. - -## Required Tools - -**Packaging/Airgapping Tool: [hauler](https://hauler.dev)** +## Required Tooling +**Packaging/Airgapping: [hauler](https://hauler.dev)** ```bash # example installation steps # please see the docs: https://rancherfederal.github.io/hauler-docs/docs/introduction/install @@ -17,8 +14,7 @@ The Carbide Secured Registry (rgcrprod.azurecr.us) is _not_ intended to be used curl -sfL https://get.hauler.dev | bash ``` -**Supply Chain Tool: [cosign](https://docs.sigstore.dev)** - +**Supply Chain Verification: [cosign](https://docs.sigstore.dev)** ```bash # example installation steps # please see the docs: https://docs.sigstore.dev/system_config/installation @@ -28,8 +24,7 @@ sudo mv cosign-linux-amd64 /usr/local/bin/cosign sudo chmod 755 /usr/local/bin/cosign ``` -**Container Tool: [helm](https://helm.sh/docs)** - +**K8s Package Management: [helm](https://helm.sh/docs)** ```bash # example installation steps # please see the docs: https://helm.sh/docs/intro/install @@ -37,3 +32,26 @@ sudo chmod 755 /usr/local/bin/cosign curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 sudo chmod 755 get_helm.sh && sudo ./get_helm.sh ``` + +## Required Artifacts + +**Carbide Public Key** +```bash +# download the public key for carbide +curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub + +# view the public key for carbide +cat carbide-key.pub + +-----BEGIN PUBLIC KEY----- +MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE5zlXeLmRxBHbVmDRZpnCFdzKhyKO +tCAZva7CLlk/6gxvCM0QkIKznfaGTRMMYTaHMdQSau6yulDLlpokA++i8Q== +-----END PUBLIC KEY----- +``` + +## Setup + +```bash +# authenticate into carbide secured registry +hauler login -u -p rgcrprod.azurecr.us +``` diff --git a/docs/registry-docs/validating-images.md b/docs/registry-docs/validating-images.md index f0b3cdd..d003521 100644 --- a/docs/registry-docs/validating-images.md +++ b/docs/registry-docs/validating-images.md @@ -2,21 +2,6 @@ This will guide you through validating the signatures and attestations of each image in the secured registry, as well as how to download artifacts about the image (Software Bill of Materials, Vulnerability Scan, Cryptographic Signature, etc...). -#### carbide-key.pub - -```bash -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub - -# view the public key for carbide -cat carbide-key.pub - ------BEGIN PUBLIC KEY----- -MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE5zlXeLmRxBHbVmDRZpnCFdzKhyKO -tCAZva7CLlk/6gxvCM0QkIKznfaGTRMMYTaHMdQSau6yulDLlpokA++i8Q== ------END PUBLIC KEY----- -``` - ## Secure Supply Chain Before pulling images or even after images have been pushed to a registry, you should always verify those images against the carbide public key. Below are the instructions for using `cosign` directly from a registry. From 15d0bb7c3dc416dd57382807d1e7f74ea6873660 Mon Sep 17 00:00:00 2001 From: clayton Date: Fri, 21 Jun 2024 16:53:52 -0700 Subject: [PATCH 04/13] migrate duplicate rancher setup instructions to rancher config section --- docs/airgapped-docs/getting-started.md | 64 ------------------------- docs/airgapped-docs/prereqs.md | 28 +++++++++-- docs/registry-docs/rancher-config.md | 48 ++++++++++++++++++- docs/stigatron-docs/getting-started.md | 65 -------------------------- docs/stigatron-docs/prereqs.md | 28 +++++++++-- 5 files changed, 96 insertions(+), 137 deletions(-) delete mode 100644 docs/airgapped-docs/getting-started.md delete mode 100644 docs/stigatron-docs/getting-started.md diff --git a/docs/airgapped-docs/getting-started.md b/docs/airgapped-docs/getting-started.md deleted file mode 100644 index 558cad8..0000000 --- a/docs/airgapped-docs/getting-started.md +++ /dev/null @@ -1,64 +0,0 @@ -# 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://rancherfederal.github.io/carbide-docs/docs/registry-docs/downloading-images). 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: - "": - auth: - username: - password: -``` diff --git a/docs/airgapped-docs/prereqs.md b/docs/airgapped-docs/prereqs.md index 578a373..35c4c09 100644 --- a/docs/airgapped-docs/prereqs.md +++ b/docs/airgapped-docs/prereqs.md @@ -3,7 +3,29 @@ 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 +- **Hauler:** https://github.com/rancherfederal/hauler +- **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). \ No newline at end of file +- Access to the `downstream` cluster(s), to be able to install and deploy the app(s). + +# 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://rancherfederal.github.io/carbide-docs/docs/registry-docs/downloading-images). 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`. diff --git a/docs/registry-docs/rancher-config.md b/docs/registry-docs/rancher-config.md index ac2e167..3a71959 100644 --- a/docs/registry-docs/rancher-config.md +++ b/docs/registry-docs/rancher-config.md @@ -1,6 +1,6 @@ # 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 (Carbide Secured Registry)** 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. @@ -16,7 +16,7 @@ This page will walk you through how to configure Rancher Manager images instead ## Configuring Cert Manager -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 your helm install of Cert Manager to use images from 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. @@ -164,3 +164,47 @@ write_files: password: permissions: '0644' ``` + +--- stuff from airgapped docs/stigatron "getting started" +## 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 STIGATRON 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: + "": + auth: + username: + password: +``` diff --git a/docs/stigatron-docs/getting-started.md b/docs/stigatron-docs/getting-started.md deleted file mode 100644 index a391864..0000000 --- a/docs/stigatron-docs/getting-started.md +++ /dev/null @@ -1,65 +0,0 @@ -# Getting Started - -This will guide you through getting started with STIGATRON. - -## STIGATRON Images - -The images for STIGATRON 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. - -## STIGATRON Helm Chart - -The chart for STIGATRON 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 STIGATRON 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: - "": - auth: - username: - password: -``` diff --git a/docs/stigatron-docs/prereqs.md b/docs/stigatron-docs/prereqs.md index d19751e..24a3f77 100644 --- a/docs/stigatron-docs/prereqs.md +++ b/docs/stigatron-docs/prereqs.md @@ -3,7 +3,29 @@ In order to utilize STIGATRON, 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 +- **Hauler:** https://github.com/rancherfederal/hauler +- **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). \ No newline at end of file +- Access to the `downstream` cluster(s), to be able to install and deploy the app(s). + +# Getting Started + +This will guide you through getting started with STIGATRON. + +## STIGATRON Images + +The images for STIGATRON 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. + +## STIGATRON Helm Chart + +The chart for STIGATRON can be found [here](../carbide-charts.md). You'll need to pull the chart using `hauler`. From f95abf15f0ef2150bb19bb1cd95f0d960acc0701 Mon Sep 17 00:00:00 2001 From: clayton Date: Fri, 21 Jun 2024 17:06:47 -0700 Subject: [PATCH 05/13] move helm chart details to configuration section --- .../configuration}/carbide-charts.md | 0 .../kubernetes.md} | 0 .../{rancher-config.md => configuration/rancher.md} | 0 sidebars.js | 12 +++++++----- 4 files changed, 7 insertions(+), 5 deletions(-) rename docs/{ => registry-docs/configuration}/carbide-charts.md (100%) rename docs/registry-docs/{kubernetes-config.md => configuration/kubernetes.md} (100%) rename docs/registry-docs/{rancher-config.md => configuration/rancher.md} (100%) diff --git a/docs/carbide-charts.md b/docs/registry-docs/configuration/carbide-charts.md similarity index 100% rename from docs/carbide-charts.md rename to docs/registry-docs/configuration/carbide-charts.md diff --git a/docs/registry-docs/kubernetes-config.md b/docs/registry-docs/configuration/kubernetes.md similarity index 100% rename from docs/registry-docs/kubernetes-config.md rename to docs/registry-docs/configuration/kubernetes.md diff --git a/docs/registry-docs/rancher-config.md b/docs/registry-docs/configuration/rancher.md similarity index 100% rename from docs/registry-docs/rancher-config.md rename to docs/registry-docs/configuration/rancher.md diff --git a/sidebars.js b/sidebars.js index 3ad91bd..214db37 100644 --- a/sidebars.js +++ b/sidebars.js @@ -61,8 +61,13 @@ const sidebars = { type: 'category', label: 'Configuration', items: [ - 'registry-docs/kubernetes-config', - 'registry-docs/rancher-config' + 'registry-docs/configuration/kubernetes', + 'registry-docs/configuration/rancher', + { + type: 'doc', + id: 'carbide-charts', + label: 'Helm Chart Configuration', + }, ], }, 'registry-docs/enforcement', @@ -76,7 +81,6 @@ const sidebars = { }, ], }, - 'carbide-charts', { type: 'category', label: 'STIGATRON', @@ -88,7 +92,6 @@ const sidebars = { label: 'Installation', items: [ 'stigatron-docs/prereqs', - 'stigatron-docs/getting-started', 'stigatron-docs/installation', ], }, @@ -114,7 +117,6 @@ const sidebars = { label: 'Installation', items: [ 'airgapped-docs/prereqs', - 'airgapped-docs/getting-started', 'airgapped-docs/installation', ], }, From 41ec60db0383252de7c67eea5ca7fc27de67036a Mon Sep 17 00:00:00 2001 From: clayton Date: Fri, 21 Jun 2024 19:26:54 -0700 Subject: [PATCH 06/13] reduce redundancy with stigatron and airgapped docs install instructions --- docs/airgapped-docs/prereqs.md | 28 +++++-------------- .../{configuration => }/carbide-charts.md | 20 ++++++------- docs/registry-docs/configuration/rancher.md | 2 +- docs/stigatron-docs/prereqs.md | 28 +++++-------------- docs/stigatron-docs/uninstall.md | 2 +- sidebars.js | 12 ++++---- 6 files changed, 31 insertions(+), 61 deletions(-) rename docs/registry-docs/{configuration => }/carbide-charts.md (75%) diff --git a/docs/airgapped-docs/prereqs.md b/docs/airgapped-docs/prereqs.md index 35c4c09..a8097d5 100644 --- a/docs/airgapped-docs/prereqs.md +++ b/docs/airgapped-docs/prereqs.md @@ -3,29 +3,15 @@ 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 -- **Hauler:** https://github.com/rancherfederal/hauler - **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). -# Getting Started +It is also assumed you have followed all of the Carbide Secured Registry (CSR) documentation. -This will guide you through getting started with Airgapped Docs. - -## Airgapped Docs Images - -The images for Airgapped Docs can be found [here](https://rancherfederal.github.io/carbide-docs/docs/registry-docs/downloading-images). 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`. +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 to run diff --git a/docs/registry-docs/configuration/carbide-charts.md b/docs/registry-docs/carbide-charts.md similarity index 75% rename from docs/registry-docs/configuration/carbide-charts.md rename to docs/registry-docs/carbide-charts.md index 7b76d44..39d2236 100644 --- a/docs/registry-docs/configuration/carbide-charts.md +++ b/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 carbide-charts/ ``` -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 < 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/configuration/rancher.md b/docs/registry-docs/configuration/rancher.md index 3a71959..a4ff708 100644 --- a/docs/registry-docs/configuration/rancher.md +++ b/docs/registry-docs/configuration/rancher.md @@ -1,6 +1,6 @@ # Rancher Manager Configuration -This page will walk you through how to configure Rancher Manager to use images from the **CSR (Carbide Secured Registry)** instead of the upstream Docker Hub images. This will apply to both 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. diff --git a/docs/stigatron-docs/prereqs.md b/docs/stigatron-docs/prereqs.md index 24a3f77..f437623 100644 --- a/docs/stigatron-docs/prereqs.md +++ b/docs/stigatron-docs/prereqs.md @@ -3,29 +3,15 @@ In order to utilize STIGATRON, you will need the following prerequisites: - **Rancher v2.7.0 or higher:** https://ranchermanager.docs.rancher.com/integrations-in-rancher/rancher-extensions -- **Hauler:** https://github.com/rancherfederal/hauler - **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). -# Getting Started +It is also assumed you have followed all of the Carbide Secured Registry (CSR) documentation. -This will guide you through getting started with STIGATRON. - -## STIGATRON Images - -The images for STIGATRON 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. - -## STIGATRON Helm Chart - -The chart for STIGATRON can be found [here](../carbide-charts.md). You'll need to pull the chart using `hauler`. +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 to run diff --git a/docs/stigatron-docs/uninstall.md b/docs/stigatron-docs/uninstall.md index 61528d6..0c36ab2 100644 --- a/docs/stigatron-docs/uninstall.md +++ b/docs/stigatron-docs/uninstall.md @@ -5,7 +5,7 @@ On the `local` cluster running Rancher MCM, run the following Helm command to remove the UI Extension. ```bash -helm uninstall -n carbide-stigatron-system stigatron-ui carbide-charts/stigatron-ui +helm uninstall -n carbide-stigatron-system stigatron-ui ``` ## Downstream Clusters diff --git a/sidebars.js b/sidebars.js index 214db37..9379ead 100644 --- a/sidebars.js +++ b/sidebars.js @@ -22,7 +22,7 @@ const sidebars = { 'intro', { type: 'category', - label: 'Carbide Secured Registry', + label: 'Carbide Secured Registry (CSR)', collapsed: false, items: [ 'registry-docs/introduction', @@ -57,17 +57,17 @@ const sidebars = { }, ], }, + { + type: 'doc', + id: 'registry-docs/carbide-charts', + label: 'Helm Charts', + }, { type: 'category', label: 'Configuration', items: [ 'registry-docs/configuration/kubernetes', 'registry-docs/configuration/rancher', - { - type: 'doc', - id: 'carbide-charts', - label: 'Helm Chart Configuration', - }, ], }, 'registry-docs/enforcement', From 43edc5b2bf48e40bc74ac954c7c41799b1febf07 Mon Sep 17 00:00:00 2001 From: clayton Date: Fri, 21 Jun 2024 19:31:42 -0700 Subject: [PATCH 07/13] remove unecessary prereq from airgapped docs install --- docs/airgapped-docs/prereqs.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/airgapped-docs/prereqs.md b/docs/airgapped-docs/prereqs.md index a8097d5..1f66c88 100644 --- a/docs/airgapped-docs/prereqs.md +++ b/docs/airgapped-docs/prereqs.md @@ -4,7 +4,6 @@ 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 - **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). It is also assumed you have followed all of the Carbide Secured Registry (CSR) documentation. From d323a36b1b9a0b538a0d19a72b028d9172a13ce5 Mon Sep 17 00:00:00 2001 From: clayton Date: Mon, 24 Jun 2024 12:18:06 -0700 Subject: [PATCH 08/13] enforcement: fix spelling, remove duplicate instructions, etc --- docs/registry-docs/enforcement.md | 18 +++--------------- 1 file changed, 3 insertions(+), 15 deletions(-) diff --git a/docs/registry-docs/enforcement.md b/docs/registry-docs/enforcement.md index cb68bb3..2716550 100644 --- a/docs/registry-docs/enforcement.md +++ b/docs/registry-docs/enforcement.md @@ -1,6 +1,6 @@ # Enforcement -This page will walk you through configuring Policy Enforcement (Kubewarden, Kyverno, Open Policy Agent) to ensure images running in your cluster that come from the hardened registry are validated against our public key before deploying. +This page will walk you through configuring a few example policy enforcement engines to validate your cluster images against our public key. This should ensure only the images from our hardened registry are allowed to run. ## Kubewarden Enforcement @@ -32,12 +32,6 @@ If your Rancher system images are in a private registry requiring authentication ### Copying Policy Artifact to a Registry (Connected Environments) ```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us - -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub - # fetch the image from the carbide secured registry hauler store add image rgcrprod.azurecr.us/policies/verify-image-signatures:v0.1.7 --key carbide-key.pub --platform linux/amd64 @@ -45,17 +39,11 @@ hauler store add image rgcrprod.azurecr.us/policies/verify-image-signatures:v0.1 hauler store copy --username --password registry:// ``` -### Saving Policy Artifact (Airgaped Environments) +### Saving Policy Artifact (Airgapped Environments) Use the below script, substituting your registry, to both validate and save locally the policy artifact: ```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us - -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub - # fetch the image from the carbide secured registry hauler store add image rgcrprod.azurecr.us/policies/verify-image-signatures:v0.1.7 --key carbide-key.pub --platform linux/amd64 @@ -63,7 +51,7 @@ hauler store add image rgcrprod.azurecr.us/policies/verify-image-signatures:v0.1 hauler store save --filename kubewarden-policy.tar.zst ``` -### Loading Policy Artifact to a Registry (Airgaped Environments) +### Loading Policy Artifact to a Registry (Airgapped Environments) Use the below script, substituting your registry, to load the policy artifact: From 25a94fb20d7a1b4a29088aaba903e6fbd53eaaf8 Mon Sep 17 00:00:00 2001 From: clayton Date: Mon, 24 Jun 2024 15:13:36 -0700 Subject: [PATCH 09/13] reorganize rancher/k8s configuration docs --- .../registry-docs/configuration/kubernetes.md | 41 ++++++ docs/registry-docs/configuration/rancher.md | 128 +++--------------- 2 files changed, 58 insertions(+), 111 deletions(-) diff --git a/docs/registry-docs/configuration/kubernetes.md b/docs/registry-docs/configuration/kubernetes.md index 6abb1a6..4619f0a 100644 --- a/docs/registry-docs/configuration/kubernetes.md +++ b/docs/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://" + configs: "": 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://" + configs: "": auth: @@ -47,3 +57,34 @@ write-kubeconfig-mode: 0640 system-default-registry: ... ``` + +#### `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://" + + configs: + "": + auth: + username: + password: + permissions: '0644' +``` diff --git a/docs/registry-docs/configuration/rancher.md b/docs/registry-docs/configuration/rancher.md index a4ff708..359e174 100644 --- a/docs/registry-docs/configuration/rancher.md +++ b/docs/registry-docs/configuration/rancher.md @@ -2,7 +2,7 @@ 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 to use images f | 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 images from the CSR. +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 < /tmp/cert-manager-values.yaml +cat < /tmp/values.yaml image: registry: 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://" - -configs: - "": - auth: - username: - password: -``` - -#### `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,71 +109,8 @@ helm install rancher carbide-charts/rancher \ --set systemDefaultRegistry= ``` -**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://" - - configs: - "": - auth: - username: - password: - permissions: '0644' -``` - ---- stuff from airgapped docs/stigatron "getting started" -## Configuring Registry Credentials - -### Local Cluster +> **NOTE:** This requires configuring RKE2/K3s `registries.yaml` to work. See the [RKE2/K3s configuration](../configuration/kubernetes.md) section for more details. -On the local cluster running Rancher Multi-cluster Manager, you'll need to configure credentials for the registry with the STIGATRON images. See the [Rancher Configuration](../registry-docs/rancher-config.md) on how to set up those credentials. +### Authenticated Registry (Manual registries.yaml) -### 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: - "": - auth: - username: - password: -``` +See the [RKE2/K3s configuration](../configuration/kubernetes.md) section for more details. From e5ed5ec2a176c89f9c4144799fb7c3d8368216fe Mon Sep 17 00:00:00 2001 From: clayton Date: Mon, 24 Jun 2024 15:19:32 -0700 Subject: [PATCH 10/13] formatting, capitalization, etc --- docs/airgapped-docs/prereqs.md | 2 +- docs/registry-docs/copying-images.md | 2 +- docs/registry-docs/introduction.md | 4 ++-- docs/registry-docs/prereqs.md | 8 ++++---- docs/registry-docs/validating-images.md | 2 +- docs/stigatron-docs/prereqs.md | 2 +- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/airgapped-docs/prereqs.md b/docs/airgapped-docs/prereqs.md index 1f66c88..a7baf40 100644 --- a/docs/airgapped-docs/prereqs.md +++ b/docs/airgapped-docs/prereqs.md @@ -13,4 +13,4 @@ This means you have: - 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 to run +- setup policy enforcement to only allow images from the CSR diff --git a/docs/registry-docs/copying-images.md b/docs/registry-docs/copying-images.md index 430c405..2c65358 100644 --- a/docs/registry-docs/copying-images.md +++ b/docs/registry-docs/copying-images.md @@ -1,6 +1,6 @@ # Copying Images to a Registry -This page will walk you through copying our secured images into your own registry for later use. +This page will walk you through hauling our secured images into your own registry for later use. If you're hauling images into an airgapped registry, check the documentation [here](downloading-images.md). diff --git a/docs/registry-docs/introduction.md b/docs/registry-docs/introduction.md index 771d478..90a6e06 100644 --- a/docs/registry-docs/introduction.md +++ b/docs/registry-docs/introduction.md @@ -7,7 +7,7 @@ As our product is still in the IOC phase, there are some expectations to level-s * IOC users can expect tooling and processes to be changed, improved and streamlined continuously as we strive to improve the Carbide offering. -**DISCLAIMER**: The Secured Registry (rgcrprod.azurecr.us) is _not_ intended to be used as the primary registry for running Kubernetes clusters. It is only intended as the acquisition point to obtain the Carbide secured images. Customers should seed their own private OCI registries, and use that registry for their Kubernetes clusters. +> **DISCLAIMER**: The Secured Registry (rgcrprod.azurecr.us) is _not_ intended to be used as the primary registry for running Kubernetes clusters. It is only intended as the acquisition point to obtain the Carbide secured images. Customers should seed their own private OCI registries, and use that registry for their Kubernetes clusters. If you see issues and areas for improvement, please submit Github issues [here](https://github.com/rancherfederal/carbide-docs/issues). @@ -31,4 +31,4 @@ The Carbide Secured Registry (CSR) was designed from the ground up to build the If we follow the SLSA level requirements using the enhancements introduced with Carbide Secured Registry (CSR), it currently puts us firmly at a SLSA level 2 (up from SLSA 0). However, the astute readers will recognize that with the current verbatim implementation of SLSA levels, level 3 and 4 are currently unobtainable due to requirements such as "accredited build platforms". -As stated earlier, the foundation for ultimately achieving SLSA 4 have been put in place to allow us to mature alongside software supply chain best practices, and standards. On that note, it's important to recognize that Carbide Secured Registry (CSR) is an ever evolving set of capabilities. Just as the standards and best practices around software supply chain security evolve, so will Carbide Secured Registry (CSR). \ No newline at end of file +As stated earlier, the foundation for ultimately achieving SLSA 4 have been put in place to allow us to mature alongside software supply chain best practices, and standards. On that note, it's important to recognize that Carbide Secured Registry (CSR) is an ever evolving set of capabilities. Just as the standards and best practices around software supply chain security evolve, so will Carbide Secured Registry (CSR). diff --git a/docs/registry-docs/prereqs.md b/docs/registry-docs/prereqs.md index 421c883..0a244f4 100644 --- a/docs/registry-docs/prereqs.md +++ b/docs/registry-docs/prereqs.md @@ -6,7 +6,7 @@ Below are all the things you need to get started with the Hardened Container Reg ## Required Tooling -**Packaging/Airgapping: [hauler](https://hauler.dev)** +**Packaging/Airgapping: [Hauler](https://hauler.dev)** ```bash # example installation steps # please see the docs: https://rancherfederal.github.io/hauler-docs/docs/introduction/install @@ -14,7 +14,7 @@ Below are all the things you need to get started with the Hardened Container Reg curl -sfL https://get.hauler.dev | bash ``` -**Supply Chain Verification: [cosign](https://docs.sigstore.dev)** +**Supply Chain Verification: [Cosign](https://docs.sigstore.dev)** ```bash # example installation steps # please see the docs: https://docs.sigstore.dev/system_config/installation @@ -24,7 +24,7 @@ sudo mv cosign-linux-amd64 /usr/local/bin/cosign sudo chmod 755 /usr/local/bin/cosign ``` -**K8s Package Management: [helm](https://helm.sh/docs)** +**K8s Package Management: [Helm](https://helm.sh/docs)** ```bash # example installation steps # please see the docs: https://helm.sh/docs/intro/install @@ -52,6 +52,6 @@ tCAZva7CLlk/6gxvCM0QkIKznfaGTRMMYTaHMdQSau6yulDLlpokA++i8Q== ## Setup ```bash -# authenticate into carbide secured registry +# log in to carbide secured registry hauler login -u -p rgcrprod.azurecr.us ``` diff --git a/docs/registry-docs/validating-images.md b/docs/registry-docs/validating-images.md index d003521..a658963 100644 --- a/docs/registry-docs/validating-images.md +++ b/docs/registry-docs/validating-images.md @@ -6,7 +6,7 @@ This will guide you through validating the signatures and attestations of each i Before pulling images or even after images have been pushed to a registry, you should always verify those images against the carbide public key. Below are the instructions for using `cosign` directly from a registry. -**NOTE:** You'll need to substitute `rgcrprod.azurecr.us` with your own registry domain, if verifying images in your own registry. +> **NOTE:** You'll need to substitute `rgcrprod.azurecr.us` with your own registry domain, if verifying images in your own registry. In Carbide Images v2 (or Cosign v2), the attachment of supply chain artifacts to the top layer of an image has been deprecated. In order for us to maintain interoperability, we have migrated our images and supply chain artifacts to be attached at the individual layer for a specific platform or architecture of an image. diff --git a/docs/stigatron-docs/prereqs.md b/docs/stigatron-docs/prereqs.md index f437623..2631458 100644 --- a/docs/stigatron-docs/prereqs.md +++ b/docs/stigatron-docs/prereqs.md @@ -14,4 +14,4 @@ This means you have: - 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 to run +- setup policy enforcement to only allow images from the CSR From a54c96801783a4caf0b5c855480bfd6234eadec1 Mon Sep 17 00:00:00 2001 From: clayton Date: Mon, 24 Jun 2024 15:33:45 -0700 Subject: [PATCH 11/13] fix: broken links --- docs/registry-docs/uninstall-kubernetes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/registry-docs/uninstall-kubernetes.md b/docs/registry-docs/uninstall-kubernetes.md index 6189cfe..738067b 100644 --- a/docs/registry-docs/uninstall-kubernetes.md +++ b/docs/registry-docs/uninstall-kubernetes.md @@ -12,7 +12,7 @@ Upon restart of your pods, they should be utilizing the upstream images. ### Reverting to DockerHub Images (Directly) -If you want to revert to using images directly from Docker Hub, you'll need to delete the `registries.yaml` configuration file made [here](kubernetes-config.md#usage-with-k3s). +If you want to revert to using images directly from Docker Hub, you'll need to delete the `registries.yaml` configuration file made [here](configuration/kubernetes.md#usage-with-k3s). You will also need to unset the `system-default-registry` configuration when installing K3s by re-running the `curl` command used to install K3s on each node, with the parameter unset. @@ -38,7 +38,7 @@ Upon restart of your pods, they should be utilizing the upstream images. ### Reverting to DockerHub Images (Directly) -If you want to revert to using images directly from Docker Hub, you'll need to delete the `registries.yaml` configuration file made [here](kubernetes-config.md#usage-with-rke2). +If you want to revert to using images directly from Docker Hub, you'll need to delete the `registries.yaml` configuration file made [here](configuration/kubernetes.md#usage-with-rke2). You'll also need to clean up the `system-default-registry` key/value from your `/etc/rancher/rke2/config.yaml` file on each node, and restart rke2. @@ -52,4 +52,4 @@ write-kubeconfig-mode: 0640 To restart controlplane nodes, run: `systemctl restart rke2-server` To restart agents, run: `systemctl restart rke2-agent` -**NOTE:** For controlplane nodes, be sure to restart them one at a time. \ No newline at end of file +**NOTE:** For controlplane nodes, be sure to restart them one at a time. From b43eac5e35a38721ecb3e4908216ac798aed3c2a Mon Sep 17 00:00:00 2001 From: clayton Date: Mon, 24 Jun 2024 15:34:43 -0700 Subject: [PATCH 12/13] fix: formatting --- docs/registry-docs/copying-images.md | 3 ++- docs/registry-docs/downloading-images.md | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/registry-docs/copying-images.md b/docs/registry-docs/copying-images.md index 2c65358..2472a01 100644 --- a/docs/registry-docs/copying-images.md +++ b/docs/registry-docs/copying-images.md @@ -6,7 +6,8 @@ If you're hauling images into an airgapped registry, check the documentation [he ## Copying Secured Images -**NOTE:** We are actively working to improve the collection and formatting of the below procceses. Additionally, please see the [Hauler Docs](https://rancherfederal.github.io/hauler-docs/docs/guides-references/hauler-content/images) for how to specify a specific platform. +>**NOTE:** We are actively working to improve the collection and formatting of the below procceses. Additionally, please see the [Hauler Docs](https://rancherfederal.github.io/hauler-docs/docs/guides-references/hauler-content/images) for how to specify a specific platform. + ### Carbide ```bash diff --git a/docs/registry-docs/downloading-images.md b/docs/registry-docs/downloading-images.md index d623358..7a47bde 100644 --- a/docs/registry-docs/downloading-images.md +++ b/docs/registry-docs/downloading-images.md @@ -8,7 +8,7 @@ If you're hauling images into a connected registry, check the documentation [her ### Carbide -**NOTE:** We are actively working to improve the collection and formatting of the below procceses. Additionally, please see the [Hauler Docs](https://rancherfederal.github.io/hauler-docs/docs/guides-references/hauler-content/images) for how to specify a specific platform. +> **NOTE:** We are actively working to improve the collection and formatting of the below procceses. Additionally, please see the [Hauler Docs](https://rancherfederal.github.io/hauler-docs/docs/guides-references/hauler-content/images) for how to specify a specific platform. ```bash # generate the hauler manifest for carbide From 8b8b26b9ef43fe2aa00fa808333d682eaa7eb357 Mon Sep 17 00:00:00 2001 From: clayton Date: Wed, 26 Jun 2024 13:03:29 -0700 Subject: [PATCH 13/13] add note for tool agnostic ops --- docs/registry-docs/copying-images.md | 6 ++++-- docs/registry-docs/downloading-images.md | 4 +++- docs/registry-docs/loading-images.md | 6 ++++-- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/registry-docs/copying-images.md b/docs/registry-docs/copying-images.md index 2472a01..e867dfd 100644 --- a/docs/registry-docs/copying-images.md +++ b/docs/registry-docs/copying-images.md @@ -1,8 +1,10 @@ # Copying Images to a Registry -This page will walk you through hauling our secured images into your own registry for later use. +This page will walk you through copying our secured images into your own registry for later use. -If you're hauling images into an airgapped registry, check the documentation [here](downloading-images.md). +> This demonstration will be using `hauler`, but any tool with the ability to push/pull an oci image will be adequate. + +If you're copying images into an airgapped registry, check the documentation [here](downloading-images.md). ## Copying Secured Images diff --git a/docs/registry-docs/downloading-images.md b/docs/registry-docs/downloading-images.md index 7a47bde..28cb5c5 100644 --- a/docs/registry-docs/downloading-images.md +++ b/docs/registry-docs/downloading-images.md @@ -2,7 +2,9 @@ This page will walk you through locally downloading our secured images from our hardened registry, as well as packaging them to move over an airgap into your registry. -If you're hauling images into a connected registry, check the documentation [here](copying-images.md). +> This demonstration will be using `hauler`, but any tool with the ability to push/pull an oci image will be adequate. + +If you're copying images into a connected registry, check the documentation [here](copying-images.md). ## Downloading Secured Images diff --git a/docs/registry-docs/loading-images.md b/docs/registry-docs/loading-images.md index 44c34b0..639f86c 100644 --- a/docs/registry-docs/loading-images.md +++ b/docs/registry-docs/loading-images.md @@ -1,8 +1,10 @@ # Loading Images to a Registry -This page will walk you through seeding your registry with local images from the hardened registry for all Rancher components. +This page will walk you through seeding your registry with downloaded images from the CSR for all Rancher components. -Make sure you've checked out the section on [Downloading Images](downloading-images.md) and that you've airgapped the tarballs onto your network. +> This demonstration will be using `hauler`, but any tool with the ability to push/pull an oci image will be adequate. + +This assumes you've followed the [downloading images](downloading-images.md) section and that you've transferred your tarballs to your airgapped environment. ## Carbide