197 update rke2 installation instructions

README.md

@@ -1,45 +1,67 @@
-# uds-bundle-software-factory-nutanix
+# UDS Bundled Software Factory for Nutanix
 
-The UDS Software Factory (SWF) bundle can be used to deploy an opinionated kubernetes based devsecops stack and development environment.
-The full list of packages and dependencies installed by the bundle (and an assumed underlying environment) can be [viewed here](docs/packages-and-dependencies.md).
+This is a UDS Software Factory bundle intended to be deployed on an RKE2 K8s cluster running in Nutanix. It has been tested using RKE2 clusters deployed with the [Nutanix RKE2 module](https://github.com/defenseunicorns/delivery-nutanix-iac/tree/main/modules/rke2).
 
-> NOTE: this project is young and rapidly iterating, stay up to date on changes by subscribing to release notifications
+A list of included applications can be found [here](docs/packages-and-dependencies.md).
 
-## Developer Info
+Bundle developers see [development.md](docs/development.md).
 
-[DEVELOPMENT_MAINTENANCE.md](docs/DEVELOPMENT_MAINTENANCE.md)
+## Installing on Nutanix
 
-## Installation ("quickstart")
+For further insight into the underlying infrastructure including the RKE2 cluster, see [the Nutanix IAC repo](https://github.com/defenseunicorns/delivery-nutanix-iac/tree/main). In particular the [UDS SWF pre-requisites documentation](https://github.com/defenseunicorns/delivery-nutanix-iac/blob/main/docs/uds-swf-prereqs.md). Note that as this bundle continues to be improved the above document may not perfectly capture the required buckets and databases. Also, buckets cannot be created in Nutanix Objects via Terraform/Tofu. Those must be created via click-ops.
 
-Once the below [Prerequisites](#prerequisites) are met, these are the steps to deploy.
+### 1. Install Required Tools
 
-- Gather your files in your working directory. Bundle tarball can be referenced via OCI or downloaded for local use.
-  - `uds-config.yaml` [Instructions on creating this file](#configuration)
-  - `uds-bundle-software-factory-nutanix-rke2-amd64-0.x.x.tar.zst` [Instructions on OCI reference usage](#deployment) or [Instructions on local reference](#optional-local-deployment-reference)
-- Deploy the bundle with the above files in your working directory by [following these instructions](#deployment)
+**To Deploy** (required):
+- [UDS CLI](https://github.com/defenseunicorns/uds-cli/tree/v0.16.0). This links to version 0.16.0 which is what the bundle is tested with but it should work with most nearby versions. The binary is here: <https://github.com/defenseunicorns/uds-cli/releases/download/v0.16.0/uds-cli_v0.16.0_Linux_amd64>
 
-### Prerequisites
 
-**Tools**:
+**To Interact with Cluster/Debug** (optional). These tools are also baked into the UDS CLI via Zarf (`uds zarf tools`) but are easier to use if installed directly:
 
-- [uds version v0.17.0](https://github.com/defenseunicorns/uds-cli/tree/v0.17.0)
-  - `sudo curl -sL https://github.com/defenseunicorns/uds-cli/releases/download/v0.17.0/uds-cli_v0.17.0_Linux_amd64`
-- (OPTIONAL) [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)
-- (OPTIONAL) [helm](https://github.com/helm/helm)
+- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)
+- [helm](https://helm.sh/docs/intro/install/)
+- [k9s](https://k9scli.io/topics/install/) also available via the command `uds monitor`
 
-**Infrastructure**:
+### 2. Get the Bundle
 
-- Kubernetes cluster
-- Access to the cluster with enough privilege to deploy
-- A valid domain
-  > NOTE: `*.bigbang.dev` may be used for demonstration and test deployments.
-- Wildcard certificates to cover your domain (alternatively, expand for full SAN list)
-  <details>
-    <summary>Individual SAN list </summary>
+Get the bundle you would like to install:
+  - You can download the latest in your browser from [Defense Unicorn's published packages](https://github.com/orgs/defenseunicorns/packages?repo_name=uds-bundle-software-factory-nutanix)
+  - You can pull it via the same protocol used to push/pull container images:
+<!--x-release-please-start-version-->
+    ```bash
+    uds pull oci://ghcr.io/defenseunicorns/uds-bundle/software-factory-nutanix-rke2:0.5.0 --architecture amd64`
+    ```
+<!--x-release-please-end-->
+  - You can also reference it by it's "docker name" (OCI image URL) at deploy time with the a similar command to the one above.
+<!--x-release-please-start-version-->
+    ```bash
+    uds deploy oci://ghcr.io/defenseunicorns/uds-bundle/software-factory-nutanix-rke2:0.5.0 --architecture amd64`
+    ```
+<!--x-release-please-end-->
+
+### 3. Customize Configuration via `uds-config.yaml`
+
+Create your own `uds-config.yaml` file. You can start from the reference file in the `config/` directory. Note it the default yaml file includes comments to point you at particular docs (such as [docs/nexus.md](docs/nexus.md)) to guide you in understanding and configuring some of the more challenging values.
+
+Don't worry about the domain, database, TLS, and object store related values at this time. They will be addressed in the following sections.
+
+### 4. Create Infrastructure Dependencies
+
+This bundle requires pre-existing s3 buckets and external postgres databases. The addresses and credentials are passed in via the `uds-config.yaml` file at deploy time.
+
+#### A. Create the Kubernetes Cluster
+
+Goes without saying, but the k8s cluster must already exist in Nutanix, and you must have admin access to it. We create ours with Terraform/Tofu [here](https://github.com/defenseunicorns/delivery-nutanix-iac/tree/main). See especially the [RKE2 module](https://github.com/defenseunicorns/delivery-nutanix-iac/tree/main/modules/rke2) and [module documentation](https://github.com/defenseunicorns/delivery-nutanix-iac/blob/main/docs/rke2-module.md).
+
+#### B. Provide a Domain, DNS sub-domain support (wildcard CNAME preferable), TLS certs
+
+During bundle development and testing, we use the `*.bigbang.dev` domain (which is owned by a Unicorn who used to work for Platform One). You will need to setup routing to `*.your-domain.com`.
+
+You also need TLS certs signed by a locally trusted CA for the applications. A wildcard cert is convenient, but many security teams prefer a cert per valid sub-domain. Here is a list of all required sub-domains:
 
   - `confluence.your.domain`
   - `gitlab.your.domain`
-  - `*.pages.your.domain`
+  - `*.pages.your.domain` **Note:** strongly recommend a wildcard here as it'd be toilsome to keep up with user behavior here.
   - `registry.your.domain`
   - `gitlab.your.domain`
   - `jira.your.domain`
@@ -49,139 +71,55 @@ Once the below [Prerequisites](#prerequisites) are met, these are the steps to d
   - `grafana.your.domain`
   - `neuvector.your.domain`
   - `nexus.your.domain`
-  - `sonarqube.your.domain`
-    - `tracing.your.domain`
-  </details>
-
-  > NOTE: If using the example domain (`*.bigbang.dev`), a valid corresponding certificate and key can be found [in the Platform1 Big Bang repo](https://repo1.dso.mil/big-bang/bigbang/-/blob/master/chart/ingress-certs.yaml?ref_type=heads).
-
-- Object Storage with provisioned buckets (expand for details).
-These are the default bucket names. Gitlab allows you to add a suffix in your `uds-config.yaml`, so reflect that if you configure a suffix. Also, Loki, Velero and Mattermost allow you to configure your bucket name in your `uds-config.yaml`. Reflect that if you configure those differently then the below defaults.
-  <details>
-    <summary> Loki </summary>
-
-  - loki-chunks-bucket
-  - loki-ruler-bucket
-  - loki-admin-bucket
-  </details>
-  <details>
-    <summary> Velero </summary>
-
-  - velero-backups
-  </details>
-  <details>
-    <summary> Gitlab </summary>
+  - `*.nexus.your.domain`
 
-  - uds-gitlab-artifacts
-  - uds-gitlab-backups
-  - uds-gitlab-ci-secure-files
-  - uds-gitlab-dependency-proxy
-  - uds-gitlab-lfs
-  - uds-gitlab-mr-diffs
-  - uds-gitlab-packages
-  - uds-gitlab-pages
-  - uds-gitlab-terraform-state
-  - uds-gitlab-uploads
-  - uds-gitlab-registry
-  - uds-gitlab-tmp
-  </details>
-  <details>
-    <summary> Mattermost </summary>
+    > **Note:** if you create your cert with a SAN per nexus subdomain instead of a wildcard SAN (need one subdomain per image registry) see [docs/nexus.md](docs/nexus.md) to make sure you update the tenant gateway and other relevant uds-config variables correctly. It was tested with a wildcard SAN on the tenant cert which allowed us to create 1-n registries without performing a bundle deploy to reconfigure networking.
 
-  - mattermost-bucket
-  </details>
-- Postgres databases (expand for details):
-  <details>
-    <summary> Full list of databases </summary>
-
-  - Keycloak
-  - Gitlab
-  - Sonarqube
-  - Jira
-  - Confluence
-  - Mattermost
-  - Nexus
-  </details>
-
-> NOTE: All database and object storage credentials must be provided via username and password in the uds-config.
-
-**Storage**:
-
-This bundle utilizes the Nutanix CSI Helm chart for persistent storage. Before the bundle can be deployed the following needs to be configured:
-
-- Prism Element user and password for the CSI provider to connect to Prism Element. Username, password, and Prism Element IP/Hostname will need passed to uds-config.yaml.
-- Nutanix Storage Container for RWO persistent volumes. Can either be a new container configured specifically for cluster storage, or an existing container depending on your needs/desires. Storage container name will need passed to uds-config.yaml.
-- Nutanix File Server configured to use for RWX persistent volumes. Make sure to configure the DNS records that it asks you to make. File Server name as it appears in Prism Element will need passed to uds-config.yaml.
-
-> NOTE: User/password and Nutanix File server must be configured in Prism Element not Prism Central.
-
-### Configuration
-
-Deployment configuration is managed via a `uds-config.yaml` file in the deployment directory. Some values in the configuration will be sensitive, **we do not recommend checking this into source control in its entirety**. Best practice would involve either storing the configuration in an external secrets manager (like Vault), or managing deployments via CD and generating the config file dynamically at deploy time using CD managed secrets.
-
-For demonstration purposes, you can setup a local configfile as follows:
-
-- Copy an example configuration from [config/uds-config.yaml](config/uds-config.yaml) to your working directory
-- Update the config according to your environment taking care to set:
-  - domain variables
-  - init variables for Nutanix csi
-  - certificate values
-  - bucket names and credentials
-  - database names and credentials
-
-> NOTE: The config must be named `uds-config.yaml` and either be present in your working directory or have the environment variable UDS_CONFIG set to its location at deploy time
-
-### Deployment
-
-Select a target version number and gather the OCI image reference [from the packages page](https://github.com/orgs/defenseunicorns/packages?repo_name=uds-bundle-software-factory-nutanix). With the above prerequisites and configuration complete, you can deploy the bundle directly via OCI:
+  - `sonarqube.your.domain`
+  - `tracing.your.domain`
 
-```bash
-uds deploy oci://ghcr.io/defenseunicorns/uds-bundle/software-factory-nutanix-rke2:0.x.x --architecture amd64 --confirm
-```
+Update the domain and TLS cert values in your `uds-config.yaml` file.
 
-### (OPTIONAL) Local Deployment Reference
+#### C. Provision S3 Compatible Object Storage
 
-Situationally, it may be useful to download the deployment artifact so that it may be referenced offline. This can be accomplished by first downloading the target release:
+There are the default bucket names in the default `uds-config.yaml` file. If you choose to deviate from these names know:
+- Gitlab only allows you to add a suffix.
+- Loki, Velero and Mattermost buckets can be named anything
 
-```bash
-uds pull oci://ghcr.io/defenseunicorns/uds-bundle/software-factory-nutanix-rke2:0.x.x --architecture amd64
-```
+Reference the `uds-config.yaml` file you created as you go to be sure you're creating/have created buckets by the intended names. For a list of UDS config variables to be sure you update, see [docs/object-store-creation-and-configuration.md](docs/object-store-creation-and-configuration.md).
 
-And subsequently deploying from the local file:
+#### D. Create the Postgres Databases.
 
-```bash
-uds deploy uds-bundle-software-factory-nutanix-rke2-amd64-0.x.x.tar.zst --confirm
-```
+The following applications require an external database:
+- Keycloak
+- Gitlab
+- Sonarqube
+- Jira
+- Confluence
+- Mattermost
+- Nexus
 
-## Custom Keycloak Plugin
+Update your `uds-config.yaml` file with the correct credentials and connection URLs. For a list of UDS config variables to be sure you update, see [docs/database-creation-and-configuration.md](docs/database-creation-and-configuration.md).
 
-The Keycloak installation provided as part of UDS Core loads themes and plugins from an init-container. You can optionally provide custom JARs at deploytime simply by adding them to the directory where you run `uds deploy`. This will result in a custom Zarf package being built locally (to include your custom JAR).
+You can review the Terraform module we use for provisioning postgres databases with Nutanix Database Service in our [delivery-nutanix-iac repo](https://github.com/defenseunicorns/delivery-nutanix-iac/tree/main/modules/ndb-pg-db).
 
-> ANY CUSTOM JAR YOU ADD AT DEPLOY TIME WILL NOT BE INCLUDED IN THE BUNDLE SBOM
+#### E. Enable Nutanix CSI
 
-## Additional Notes
+This bundle utilizes the Nutanix CSI Helm chart for persistent storage. It needs Nutanix resources set up ahead of time.
 
-You can reference the uds tasks in this project to learn how to build and deploy.
+1. Prism Element user and password for the CSI provider to connect to Prism Element. Update your `uds-config.yaml` file with the user credentials and the Prism Element IP/Hostname.
+2. Prism Central user and password for the CSI provider to connect to Prism Central. Update your `uds-config.yaml` file with the user credentials and the Prism Central IP/Hostname.
+3. Nutanix Storage Container for RWO persistent volumes. Add the storage container name to the `uds-config.yaml`.
+4. Nutanix File Server for RWX persistent volumes. **Be sure to configure the DNS records that it asks for.** Put the File Server name as it appears in Prism Element into your `uds-config.yaml`.
 
-```bash
-# List the available tasks to run
-uds run --list
-```
+> NOTE: User/password and Nutanix File server must be configured in Prism _Element_ not Prism _Central_.
 
-To force terminate a namespace that is hanging, try this. This state is often brought about during development by deleting the metrics
-server before everything else is gone. The namespaces then hang as they're unable to talk to it.
+### 5. Deploy
 
-```bash
-kubectl proxy & # Only run this once
-destroy-ns () {
-  NAMESPACE="${1}"
-  kubectl get namespace "${NAMESPACE}" -o json | jq '.spec = {"finalizers":[]}' > temp.json
-  curl -k -H "Content-Type: application/json" -X PUT --data-binary @temp.json 127.0.0.1:8001/api/v1/namespaces/$NAMESPACE/finalize
-}
+This is the easy step.
 
-# For every namespace you want to delete:
-destroy-ns <namespace>
+1. Set `KUBECONFIG` to point to the kubernetes kubeconfig file.
+2. Set `UDS_CONFIG` to point at your `uds-config.yaml` file.
+3. Run `uds deploy <package file name or OCI url> --architecure amd64`.
 
-# So we don't dirty the git history
-rm temp.json
-```
+If you got the config right the first time, then congratulations! The whole thing is now running. If murphy struck, see the [developer docs](docs/development.md) for guidance on efficiently testing configuration changes, setting up multiple clusters in a way that fits with the uds tasks, and other notes.