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..a7baf40 100644 --- 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). \ No newline at end of file +- **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 b/docs/registry-docs/carbide-charts.md similarity index 75% rename from docs/carbide-charts.md rename to docs/registry-docs/carbide-charts.md index 7b76d44..39d2236 100644 --- a/docs/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/kubernetes-config.md b/docs/registry-docs/configuration/kubernetes.md similarity index 57% rename from docs/registry-docs/kubernetes-config.md rename to docs/registry-docs/configuration/kubernetes.md index 6abb1a6..4619f0a 100644 --- a/docs/registry-docs/kubernetes-config.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/rancher-config.md b/docs/registry-docs/configuration/rancher.md similarity index 56% rename from docs/registry-docs/rancher-config.md rename to docs/registry-docs/configuration/rancher.md index ac2e167..359e174 100644 --- a/docs/registry-docs/rancher-config.md +++ b/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 < /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,27 +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' -``` +> **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. diff --git a/docs/registry-docs/copying-images.md b/docs/registry-docs/copying-images.md index 7323673..e867dfd 100644 --- a/docs/registry-docs/copying-images.md +++ b/docs/registry-docs/copying-images.md @@ -1,20 +1,18 @@ # 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). +> This demonstration will be using `hauler`, but any tool with the ability to push/pull an oci image will be adequate. -## Carbide +If you're copying images into an airgapped registry, check the documentation [here](downloading-images.md). -**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. +## Copying Secured Images -```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us +>**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. -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub +### Carbide +```bash # generate the hauler manifest for carbide cat < carbide-images.yaml apiVersion: content.hauler.cattle.io/v1alpha1 @@ -45,15 +43,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 +54,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 +64,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 +77,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 +88,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 +99,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 +110,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..28cb5c5 100644 --- a/docs/registry-docs/downloading-images.md +++ b/docs/registry-docs/downloading-images.md @@ -1,20 +1,18 @@ # 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). +> This demonstration will be using `hauler`, but any tool with the ability to push/pull an oci image will be adequate. -## Carbide +If you're copying images into a connected registry, check the documentation [here](copying-images.md). -**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. +## Downloading Secured Images -```bash -# authenticate into carbide secured registry -hauler login -u -p rgcrprod.azurecr.us +### Carbide -# download the public key for carbide -curl -sfOL https://raw.githubusercontent.com/rancherfederal/carbide-releases/main/carbide-key.pub +> **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 +43,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 +54,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 +65,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 +78,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 +89,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 +100,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 +111,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/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: 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/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 diff --git a/docs/registry-docs/prereqs.md b/docs/registry-docs/prereqs.md index 234ea21..0a244f4 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 +# log in to carbide secured registry +hauler login -u -p rgcrprod.azurecr.us +``` 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. diff --git a/docs/registry-docs/validating-images.md b/docs/registry-docs/validating-images.md index 2f28a2b..a658963 100644 --- a/docs/registry-docs/validating-images.md +++ b/docs/registry-docs/validating-images.md @@ -2,34 +2,19 @@ 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. -**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) +> **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. 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 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..2631458 100644 --- a/docs/stigatron-docs/prereqs.md +++ b/docs/stigatron-docs/prereqs.md @@ -3,7 +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 -- For fetching and packaging... **Hauler:** https://github.com/rancherfederal/hauler -- For installation and deployment... **Helm:** https://helm.sh/docs/intro/install +- **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). + +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/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 80a101a..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', @@ -36,28 +36,38 @@ 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', + ], + }, ], }, ], }, + { + type: 'doc', + id: 'registry-docs/carbide-charts', + label: 'Helm Charts', + }, { type: 'category', label: 'Configuration', items: [ - 'registry-docs/kubernetes-config', - 'registry-docs/rancher-config' + 'registry-docs/configuration/kubernetes', + 'registry-docs/configuration/rancher', ], }, 'registry-docs/enforcement', @@ -71,7 +81,6 @@ const sidebars = { }, ], }, - 'carbide-charts', { type: 'category', label: 'STIGATRON', @@ -83,7 +92,6 @@ const sidebars = { label: 'Installation', items: [ 'stigatron-docs/prereqs', - 'stigatron-docs/getting-started', 'stigatron-docs/installation', ], }, @@ -109,7 +117,6 @@ const sidebars = { label: 'Installation', items: [ 'airgapped-docs/prereqs', - 'airgapped-docs/getting-started', 'airgapped-docs/installation', ], },