chore(docs): update doc structure for site refresh (#895)

## Description This PR changes the docs structure to reflect the updated site architecture. - ADRs moved to a separate folder - All docs are served out of `docs/reference` (or possibly `docs/troubleshooting` if added) - Remove unnecessary front matter as needed ## Related Issue N/A ## Type of change - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [X] Other (security config, docs update, etc) ## Checklist before merging - [ ] Test, docs, adr added or updated as needed - [ ] [Contributor Guide](https://github.com/defenseunicorns/uds-template-capability/blob/main/CONTRIBUTING.md) followed --------- Co-authored-by: Micah Nagel <[email protected]>
defenseunicorns · Oct 11, 2024 · 1946a9a · 1946a9a
1 parent 6e47b11
commit 1946a9a
Show file tree

Hide file tree

Showing 22 changed files with 25 additions and 219 deletions.
diff --git a/docs/adrs/.gitkeep → adrs/.gitkeep b/docs/adrs/.gitkeep → adrs/.gitkeep
diff --git a/...drs/0001-record-architecture-decisions.md → adrs/0001-record-architecture-decisions.md b/...drs/0001-record-architecture-decisions.md → adrs/0001-record-architecture-decisions.md
diff --git a/docs/adrs/0002-uds-core-functional-layers.md → adrs/0002-uds-core-functional-layers.md b/docs/adrs/0002-uds-core-functional-layers.md → adrs/0002-uds-core-functional-layers.md
diff --git a/docs/application-baseline.md b/docs/application-baseline.md
diff --git a/docs/configuration/_index.md b/docs/configuration/_index.md
diff --git a/docs/configuration/istio/_index.md b/docs/configuration/istio/_index.md
diff --git a/docs/deployment/_index.md b/docs/deployment/_index.md
diff --git a/docs/deployment/uds-deploy.md b/docs/deployment/uds-deploy.md
diff --git a/docs/development/_index.md b/docs/development/_index.md
diff --git a/docs/deployment/distribution-support.md → ...eference/UDS Core/distribution-support.md b/docs/deployment/distribution-support.md → ...eference/UDS Core/distribution-support.md
@@ -1,7 +1,5 @@
 ---
 title: Distribution Support
-type: docs
-weight: 1
 ---
 
 UDS Core is a versatile software baseline designed to operate effectively across a variety of Kubernetes distributions. While it is not specifically tailored to any single Kubernetes distribution, it is compatible with multiple environments. This documentation provides an overview of UDS Core's compatibility with different distributions and the level of support provided.
@@ -12,8 +10,8 @@ UDS Core is a versatile software baseline designed to operate effectively across
 
 - **Compatible:** Kubernetes distributions listed under this category may not have undergone extensive testing in UDS Core's CI environments. While UDS Core may be compatible on these distributions, users should exercise caution and be prepared for potential compatibility issues or limitations.
 
-| Distribution        | Category               | Support Level                                                                                             |
-| ------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------- |
+| Distribution    | Category               | Support Level                                                                                             |
+| --------------- | ---------------------- | --------------------------------------------------------------------------------------------------------- |
 | K3d/K3s, Amazon EKS | Tested                 | Supported Kubernetes distributions undergoing testing in CI environments.                                 |
-| RKE2                | Tested                 | Supported Kubernetes distribution tested in production environments other than CI.                        |
-| Other               | Untested/Unknown state | Compatible Kubernetes distributions that are not explicitly tested, documented, or supported by UDS Core. |
+| RKE2            | Tested                 | Supported Kubernetes distribution tested in production environments other than CI.                        |
+| Other           | Untested/Unknown state | Compatible Kubernetes distributions that are not explicitly tested, documented, or supported by UDS Core. |
diff --git a/docs/deployment/dns.md → docs/reference/UDS Core/dns.md b/docs/deployment/dns.md → docs/reference/UDS Core/dns.md
diff --git a/docs/development/flavor-specific-dev.md → ...Core/flavor-specific-development-notes.md b/docs/development/flavor-specific-dev.md → ...Core/flavor-specific-development-notes.md
@@ -1,7 +1,5 @@
 ---
 title: Flavor Specific Development Notes
-type: docs
-weight: 5
 ---
 
 Specific flavors of UDS Core have access and architecture restrictions when used for development work. The `upstream` flavor is generally recommended for development as it does not have any restrictions or requirements.

diff --git a/docs/_index.md → docs/reference/UDS Core/overview.md b/docs/_index.md → docs/reference/UDS Core/overview.md
@@ -1,10 +1,7 @@
 ---
-title: UDS Core
-linkTitle: UDS Core
-type: docs
-menu:
-  main:
-    weight: 30
+title: Overview
+sidebar:
+    order: 1
 ---
 
 ## What is UDS Core?

diff --git a/docs/deployment/prerequisites.md → docs/reference/UDS Core/prerequisites.md b/docs/deployment/prerequisites.md → docs/reference/UDS Core/prerequisites.md
@@ -1,11 +1,7 @@
 ---
 title: UDS Core Prerequisites
-type: docs
-weight: 4
 ---
 
-## UDS Core Prerequisites
-
 `UDS Core` can run in any [CNCF conformant Kubernetes distribution](https://www.cncf.io/training/certification/software-conformance/), but sometimes customizations are needed based on environments. This is an attempt to document and link to relevant information to aid in setting up your Kubernetes environment and hosts to ensure a successful `UDS Core` installation.  
 
 ### Cluster Requirements

diff --git a/docs/configuration/istio/ingress.md → docs/reference/configuration/ingress.md b/docs/configuration/istio/ingress.md → docs/reference/configuration/ingress.md
@@ -1,7 +1,5 @@
 ---
-title: Configuring Istio Ingress
-type: docs
-weight: 1
+title: Istio Ingress
 ---
 
 UDS Core leverages Istio for ingress into the service mesh. This document provides an overview and examples of the Istio resources that UDS Core deploys to handle ingress.
@@ -46,14 +44,17 @@ metadata:
   name: core-with-cert-override
   description: A UDS example bundle for packaging UDS core with a custom TLS certificate
   version: "0.0.1"
-  
+
 packages:
   - name: core
     repository: oci://ghcr.io/defenseunicorns/packages/uds/core
     ref: 0.23.0-upstream
     overrides:
       istio-admin-gateway:
         uds-istio-config:
+          values:
+            - path: tls.supportTLSV1_2
+              value: true # Add support for TLS 1.2 on this gateway, can be specified via variables if needed at deploy time
           variables:
             - name: ADMIN_TLS_CERT
               description: "The TLS cert for the admin gateway (must be base64 encoded)"
@@ -63,9 +64,6 @@ packages:
               path: tls.key
       istio-tenant-gateway:
         uds-istio-config:
-          values:
-            - path: tls.supportTLSV1_2
-              value: true # Add support for TLS 1.2 on this gateway, can be specified via variables if needed at deploy time
           variables:
             - name: TENANT_TLS_CERT
               description: "The TLS cert for the tenant gateway (must be base64 encoded)"
@@ -84,14 +82,14 @@ shared:
   domain: yourawesomedomain.com # shared across all packages in a bundle
 
 # TLS Certs/Keys if not provided via environment variables
-variables: 
+variables:
   core:
     admin_tls_cert: # base64 encoded admin cert here
     admin_tls_key: # base64 encoded admin key here
     tenant_tls_cert: # base64 encoded tenant cert here
     tenant_tls_key: # base64 encoded tenant key here
 ```
 
-{{% alert-note %}}
+:::note
 If you are using Private PKI or self-signed certificates for your tenant certificates it is necessary to additionally configure `UDS_CA_CERT` with additional [trusted certificate authorities](https://uds.defenseunicorns.com/core/configuration/uds-operator/#trusted-certificate-authority).
-{{% /alert-note %}}
+:::
diff --git a/docs/configuration/pepr-policies.md → .../reference/configuration/pepr-policies.md b/docs/configuration/pepr-policies.md → .../reference/configuration/pepr-policies.md
@@ -1,7 +1,5 @@
 ---
 title: Pepr Policies
-type: docs
-weight: 3
 ---
 
 ## Common Pepr Policies for UDS Core

diff --git a/...guration/resource-configuration-and-ha.md → ...guration/resource-configuration-and-ha.md b/...guration/resource-configuration-and-ha.md → ...guration/resource-configuration-and-ha.md
@@ -1,7 +1,5 @@
 ---
 title: Resource Configuration and High Availability
-type: docs
-weight: 3.5
 ---
 
 Depending on your environment and the scale of your cluster, you might need to adjust UDS Core components for high availability or to optimize resources. Below are common areas where resource overrides can be useful when deploying UDS Core.

diff --git a/...ration/uds-configure-policy-exemptions.md → ...ration/uds-configure-policy-exemptions.md b/...ration/uds-configure-policy-exemptions.md → ...ration/uds-configure-policy-exemptions.md
@@ -1,7 +1,5 @@
 ---
 title: Configuring Policy Exemptions
-type: docs
-weight: 4
 ---
 
 By default policy exemptions ([UDSExemptions](https://github.com/defenseunicorns/uds-core/blob/uds-docs/src/pepr/operator/crd/generated/exemption-v1alpha1.ts)) are only allowed in a single namespace -- `uds-policy-exemptions`. We recognize this is not a conventional pattern in K8s, but believe it is ideal for UDS for the following reasons:

diff --git a/docs/configuration/uds-monitoring-metrics.md → ...e/configuration/uds-monitoring-metrics.md b/docs/configuration/uds-monitoring-metrics.md → ...e/configuration/uds-monitoring-metrics.md
@@ -1,7 +1,5 @@
 ---
 title: Monitoring and Metrics
-type: docs
-weight: 1
 ---
 
 UDS Core leverages Pepr to handle setup of Prometheus scraping metrics endpoints, with the particular configuration necessary to work in a STRICT mTLS (Istio) environment. We handle this via a default scrapeClass in prometheus to add the istio certs. When a monitor needs to be exempt from that tlsConfig a mutation is performed to leverage a plain scrape class without istio certs.
@@ -14,9 +12,9 @@ Generally it is beneficial to use service and pod monitor resources from existin
 1. Individual monitors can explicitly set the `exempt` scrape class to opt out of the Istio certificate configuration. This should typically only be done if your service exposes metrics on a PERMISSIVE mTLS port.
 1. If setting a `scrapeClass` is not an option due to lack of configuration in a helm chart, or for other reasons, monitors can use the `uds/skip-mutate` annotation (with any value) to have Pepr mutate the `exempt` scrape class onto the monitor.
 
-{{% alert-note %}}
+:::note
 There is a deprecated functionality in Pepr that will mutate `tlsConfig` onto individual service monitors, rather than using the scrape class approach. This has been kept in the current code temporarily to prevent any metrics downtime during the switch to `scrapeClass`. In a future release this behavior will be removed to reduce the complexity of the setup and required mutations.
-{{% /alert-note %}}
+:::
 
 ## Package CR `monitor` field
 

diff --git a/docs/configuration/uds-operator.md → docs/reference/configuration/uds-operator.md b/docs/configuration/uds-operator.md → docs/reference/configuration/uds-operator.md
@@ -1,7 +1,5 @@
 ---
 title: UDS Operator
-type: docs
-weight: 2
 ---
 
 The UDS Operator plays a pivotal role in managing the lifecycle of UDS Package Custom Resources (CRs) along with their associated resources like NetworkPolicies and Istio VirtualServices. Leveraging [Pepr](https://github.com/defenseunicorns/pepr), the operator binds watch operations to the enqueue and reconciler, taking on several key responsibilities for UDS Packages and exemptions:
@@ -163,9 +161,9 @@ spec:
         app: httpbin
 ```
 
-{{% alert-note %}}
+:::note
 The UDS Operator uses the first `redirectUris` to populate the `match.prefix` hostname and `callback_uri` in the authservice chain.
-{{% /alert-note %}}
+:::
 
 For a complete example, see [app-authservice-tenant.yaml](https://github.com/defenseunicorns/uds-core/blob/main/src/test/app-authservice-tenant.yaml)
 

diff --git a/docs/configuration/uds-user-groups.md → ...eference/configuration/uds-user-groups.md b/docs/configuration/uds-user-groups.md → ...eference/configuration/uds-user-groups.md
@@ -1,7 +1,5 @@
 ---
 title: User Groups
-type: docs
-weight: 5
 ---
 
 UDS Core deploys Keycloak which has some preconfigured groups that applications inherit from SSO and IDP configurations.
@@ -30,9 +28,9 @@ Neuvector [maps the groups](https://github.com/defenseunicorns/uds-core/blob/mai
 
 ## Keycloak
 
-{{% alert-note %}}
+:::note
 All groups are under the Uds Core parent group. Frequently a group will be referred to as Uds Core/Admin or Uds Core/Auditor. In the Keycloak UI this requires an additional click to get down to the sub groups.
-{{% /alert-note %}}
+:::
 
 ### Identity Providers ( IDP )