feat: uds core docs

docs/_index.md

@@ -0,0 +1,30 @@
+---
+title: UDS Core
+linkTitle: UDS Core
+type: docs
+menu:
+  main:
+    weight: 30
+---
+
+## What is UDS Core?
+
+UDS Core is a collection of several individual applications combined into a single Zarf Package, that establishes a secure baseline for secure cloud-native systems. It comes equipped with comprehensive compliance documentation and prioritizes seamless support for highly regulated and egress-limited environments. Building upon the achievements of Platform One, UDS Core enhances the security stance introduced by Big Bang. It introduces advanced automation through the UDS Operator and UDS Policy Engine.
+
+UDS Core enables your team to:
+
+- Deploy full mission environments and applications efficiently and securely.
+- Leverage specific functional applications to deliver a versatile platform that caters to diverse mission objectives.
+- Enhance the efficiency, security, and success of software delivery and operations process.
+
+### Accomplishing Mission Objectives with Functional Applications
+
+UDS leverages functional applications that are well-suited to perform the specific tasks required. These tools are carefully selected to ensure optimal performance and compatibility within the UDS landscape. By integrating functional tools into the platform, UDS ensures that Mission Heroes have access to cutting-edge technologies and best-in-class solutions for their missions.
+
+### Leveraging UDS Applications
+
+Mission Heroes can leverage UDS Core Applications to tailor their mission environment and meet their unique requirements. By selecting and integrating specific tools into their deployments, your team can achieve a streamlined and secure software delivery process. Ranging from setting up a DevSecOps pipeline, enforcing security policies, or managing user identities, UDS Applications provide the necessary tools to accomplish mission objectives effectively.
+
+### UDS Core Dependency
+
+A UDS Core dependency refers to the specific prerequisites and external elements required for the smooth operation of bundled tools. While UDS Applications are designed to offer distinct functionalities, some may necessitate external resources, services, or configurations to seamlessly integrate within a particular environment. These dependencies can include a wide range of components such as databases, security services, and networking tools.

docs/application-baseline.md

@@ -0,0 +1,25 @@
+---
+title: Application Baseline
+type: docs
+weight: 1
+---
+
+UDS Core provides a foundational set of applications that form the backbone of a secure and efficient mission environment. Each application addresses critical aspects of microservices communication, monitoring, logging, security, compliance, and data protection. These applications are essential for establishing a reliable runtime environment and ensuring that mission-critical applications operate seamlessly.
+
+By leveraging these applications within UDS Core, users can confidently deploy and operate source packages that meet stringent security and performance standards. UDS Core provides the applications and flexibility required to achieve diverse mission objectives, whether in cloud, on-premises, or edge environments. UDS source packages cater to the specific needs of Mission Heroes and their mission-critical operations. Below are some of the key applications offered by UDS Core:
+
+{{% alert-note %}}
+For optimal deployment and operational efficiency, it is important to deliver a UDS Core Bundle before deploying any other optional bundle (UDS or Mission). Failure to meet this prerequisite can alter the complexity of the deployment process. To ensure a seamless experience and to leverage the full potential of UDS capabilities, prioritize the deployment of UDS Core as the foundational step.
+{{% /alert-note %}}
+
+## Core Baseline
+
+| **Capability**                     | **Application**                                                                                                                                                                                                                                                                                                                                       |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Service Mesh**                   | **Istio:** A powerful service mesh tool that provides traffic management, load balancing, security, and observability features.                                                                                                                                                                                                                       |
+| **Monitoring**                     | **Prometheus Stack:** Collects and stores time-series data for insights into application health and performance.<br><br> **Grafana:** Provides visualization and alerting capabilities for monitoring metrics.<br><br> **Metrics Server:** Offers resource utilization metrics for Kubernetes clusters, aiding in capacity planning and optimization. |
+| **Logging**                        | **Loki:** A log aggregation system that allows users to store, search, and analyze logs across their applications.<br><br> **Promtail:** A companion agent that efficiently gathers and sends log data to Loki, simplifying log monitoring, troubleshooting, and compliance auditing, enhancing the overall observability of the mission environment. |
+| **Security and Compliance**        | **NeuVector:** Offers container-native security, protecting applications against threats and vulnerabilities.<br><br> **Pepr:** UDS policy engine and operator for enhanced security and compliance.                                                                                                                                                  |
+| **Identity and Access Management** | **Keycloak:** A robust open-source Identity and Access Management solution, providing centralized authentication, authorization, and user management for enhanced security and control over access to mission-critical resources.                                                                                                                     |
+| **Backup and Restore**             | **Velero:** Provides backup and restore capabilities for Kubernetes clusters, ensuring data protection and disaster recovery.                                                                                                                                                                                                                         |
+| **Authorization**                  | **AuthService:** Offers centralized authorization services, managing access control and permissions within the mission environment.                                                                                                                                                                                                                   |

docs/configuration/_index.md

@@ -0,0 +1,5 @@
+---
+title: Configure UDS Core
+type: docs
+weight: 3
+---

docs/CONFIGURE_POLICY_EXEMPTIONS.md → docs/configuration/uds-configure-policy-exemptions.md

@@ -1,11 +1,14 @@
-## Configuring UDS-CORE Policy Exemptions
+---
+title: Configuring Policy Exemptions
+type: docs
+weight: 3
+---
 
-By default policy exemptions ([UDSExemptions](../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:
+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:
 
 - highlights the fact that an exemption can reduce the overall security posture of the cluster 
 - makes maintaining RBAC for controlling exemptions more straightforward
 - reduces the risk that an unintentional mis-configuration of RBAC allows a cluster exemption that would otherwise be denied
-
 ## Allow All Namespaces
 
 If you believe that the default scoping is not the right approach for your cluster, you can configure UDS-CORE at deploy time to allow exemption CRs in all namespaces.

docs/MONITOR.md → docs/configuration/uds-monitoring-metrics.md

@@ -1,4 +1,8 @@
-# Monitoring / Metrics Scraping in UDS Core
+---
+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 with both mutations of existing service monitors and generation of service monitors via the `Package` CR. 
 

docs/configuration/uds-operator.md

@@ -0,0 +1,205 @@
+---
+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:
+
+## Package
+
+- **Enabling Istio Sidecar Injection:**
+  - The operator facilitates the activation of Istio sidecar injection within namespaces where the CR is deployed.
+- **Establishing Default-Deny Ingress/Egress Network Policies:**
+  - It sets up default-deny network policies for both ingress and egress, creating a foundational security posture.
+- **Implementing Layered Allow-List Approach:**
+  - A layered allow-list approach is applied on top of default-deny network policies. This includes essential defaults like Istio requirements and DNS egress.
+- **Providing Targeted Remote Endpoints Network Policies:**
+  - The operator creates targeted network policies for remote endpoints, such as `KubeAPI` and `CloudMetadata`. This approach aims to enhance policy management by reducing redundancy (DRY) and facilitating dynamic bindings in scenarios where static definitions are impractical.
+- **Creating Istio Virtual Services and Related Ingress Gateway Network Policies:**
+  - In addition, the operator is responsible for generating Istio Virtual Services and the associated network policies for the ingress gateway.
+
+### Example UDS Package CR
+
+```yaml
+apiVersion: uds.dev/v1alpha1
+kind: Package
+metadata:
+  name: grafana
+  namespace: grafana
+spec:
+  network:
+    # Expose rules generate Istio VirtualServices and related network policies
+    expose:
+      - service: grafana
+        selector:
+          app.kubernetes.io/name: grafana
+        host: grafana
+        gateway: admin
+        port: 80
+        targetPort: 3000
+
+    # Allow rules generate NetworkPolicies
+    allow:
+      - direction: Egress
+        selector:
+          app.kubernetes.io/name: grafana
+        remoteGenerated: Anywhere
+
+      - direction: Egress
+        remoteNamespace: tempo
+        remoteSelector:
+          app.kubernetes.io/name: tempo
+        port: 9411
+        description: "Tempo"
+
+  # SSO allows for the creation of Keycloak clients and with automatic secret generation
+  sso:
+    - name: Grafana Dashboard
+      clientId: uds-core-admin-grafana
+      redirectUris:
+        - "https://grafana.admin.uds.dev/login/generic_oauth"
+```
+
+## Exemption
+
+- **Exemption Scope:**
+  - Granting exemption for custom resources is restricted to the `uds-policy-exemptions` namespace by default, unless specifically configured to allow exemptions across all namespaces.
+- **Policy Updates:**
+  - Updating the policies Pepr store with registered exemptions.
+
+### Example UDS Exemption CR
+
+```yaml
+apiVersion: uds.dev/v1alpha1
+kind: Exemption
+metadata:
+  name: neuvector
+  namespace: uds-policy-exemptions
+spec:
+  exemptions:
+    - policies:
+        - DisallowHostNamespaces
+        - DisallowPrivileged
+        - RequireNonRootUser
+        - DropAllCapabilities
+        - RestrictHostPathWrite
+        - RestrictVolumeTypes
+      matcher:
+        namespace: neuvector
+        name: "^neuvector-enforcer-pod.*"
+
+    - policies:
+        - DisallowPrivileged
+        - RequireNonRootUser
+        - DropAllCapabilities
+        - RestrictHostPathWrite
+        - RestrictVolumeTypes
+      matcher:
+        namespace: neuvector
+        name: "^neuvector-controller-pod.*"
+
+    - policies:
+        - DropAllCapabilities
+      matcher:
+        namespace: neuvector
+        name: "^neuvector-prometheus-exporter-pod.*"
+```
+
+### Example UDS Package CR with SSO Templating
+
+By default, UDS generates a secret for the Single Sign-On (SSO) client that encapsulates all client contents as an opaque secret. In this setup, each key within the secret corresponds to its own environment variable or file, based on the method used to mount the secret. If customization of the secret rendering is required, basic templating can be achieved using the `secretTemplate` property. Below are examples showing this functionality. To see how templating works, please see the [Regex website](https://regex101.com/r/e41Dsk/3).
+
+```yaml
+apiVersion: uds.dev/v1alpha1
+kind: Package
+metadata:
+  name: grafana
+  namespace: grafana
+spec:
+  sso:
+    - name: My Keycloak Client
+      clientId: demo-client
+      redirectUris:
+        - "https://demo.uds.dev/login"
+      # Customize the name of the generated secret
+      secretName: my-cool-auth-client
+      secretTemplate:
+        # Raw text examples
+        rawTextClientId: "clientField(clientId)"
+        rawTextClientSecret: "clientField(secret)"
+
+        # JSON example
+        auth.json: |
+          {
+            "client_id": "clientField(clientId)",
+            "client_secret": "clientField(secret)",
+            "defaultScopes": clientField(defaultClientScopes).json(),
+            "redirect_uri": "clientField(redirectUris)[0]",
+            "bearerOnly": clientField(bearerOnly),
+          }
+
+        # Properties example
+        auth.properties: |
+          client-id=clientField(clientId)
+          client-secret=clientField(secret)
+          default-scopes=clientField(defaultClientScopes)
+          redirect-uri=clientField(redirectUris)[0]
+
+        # YAML example (uses JSON for the defaultScopes array)
+        auth.yaml: |
+          client_id: clientField(clientId)
+          client_secret: clientField(secret)
+          default_scopes: clientField(defaultClientScopes).json()
+          redirect_uri: clientField(redirectUris)[0]
+          bearer_only: clientField(bearerOnly)
+  ```
+
+### Configuring UDS Core Policy Exemptions
+
+Default [policy exemptions](https://github.com/defenseunicorns/uds-core/blob/main/src/pepr/operator/crd/generated/exemption-v1alpha1.ts) are confined to a singular namespace: `uds-policy-exemptions`. We find this to be an optimal approach for UDS due to the following reasons:
+
+- **Emphasis on Security Impact:**
+  - An exemption has the potential to diminish the overall security stance of the cluster. By isolating these exemptions within a designated namespace, administrators can readily recognize and assess the security implications associated with each exemption.
+- **Simplified RBAC Maintenance:**
+  - Adopting this pattern streamlines the management of Role-Based Access Control (RBAC) for overseeing exemptions. Placing all UDS exemptions within a dedicated namespace simplifies the task of configuring and maintaining RBAC policies, enhancing overall control and transparency.
+- **Mitigation of Configuration Risks:**
+  - By restricting exemptions to a specific namespace, the risk of unintentional misconfigurations in RBAC is significantly reduced. This ensures that cluster exemptions are only granted intentionally and within the confines of the designated namespace, minimizing the potential for security vulnerabilities resulting from misconfigured permissions.
+
+### Allow All Namespaces
+
+If you find that the default scoping is not the right approach for your cluster, you have the option to configure `UDS-CORE` at deploy time to allow exemption CRs in all namespaces:
+
+`zarf package deploy zarf-package-uds-core-*.zst --set ALLOW_ALL_NS_EXEMPTIONS=true`
+
+You can also achieve this through the `uds-config.yaml`:
+
+```yaml
+options:
+  # options here
+
+shared:
+   ALLOW_ALL_NS_EXEMPTIONS: "true"
+
+variables:
+ # package specific variables here
+```
+
+## Key Files and Folders
+
+```dir
+src/pepr/operator/
+├── controllers             # Core business logic called by the reconciler
+│   ├── exemptions          # Manages updating Pepr store with exemptions from UDS Exemption
+│   ├── istio               # Manages Istio VirtualServices and sidecar injection for UDS Packages/Namespace
+│   ├── keycloak            # Manages Keycloak client syncing
+│   └── network             # Manages default and generated NetworkPolicies for UDS Packages/Namespace
+├── crd
+│   ├── generated           # Type files generated by `uds run -f src/pepr/tasks.yaml gen-crds`
+│   ├── sources             # CRD source files
+│   ├── migrate.ts          # Migrates older versions of UDS Package CRs to new version
+│   ├── register.ts         # Registers the UDS Package CRD with the Kubernetes API
+│   └── validators          # Validates Custom Resources with Pepr
+├── index.ts                # Entrypoint for the UDS Operator
+└── reconcilers             # Reconciles Custom Resources via the controllers
+```

docs/UDS_CORE_GROUPS.md → docs/configuration/uds-user-groups.md

@@ -1,4 +1,8 @@
-# UDS-CORE Groups
+---
+title: User Groups
+type: docs
+weight: 4
+---
 
 UDS Core deploys Keycloak which has some preconfigured groups that applications inherit from SSO and IDP configurations.
 
@@ -21,9 +25,10 @@ Neuvector [maps the groups](https://github.com/defenseunicorns/uds-core/blob/mai
 | `Admin`        | `admin`                |
 | `Auditor`      | `reader`               |
 
-## Keycloak 
-> [!IMPORTANT]
-> 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.
+## Keycloak
+{{% alert-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 )
 

docs/deployment/_index.md

@@ -0,0 +1,5 @@
+---
+title: Deploying UDS Core
+type: docs
+weight: 2
+---