From 1946a9a8144a0cd383c3af29c33bb828283ef81d Mon Sep 17 00:00:00 2001 From: Paul Di Pietro Date: Fri, 11 Oct 2024 12:16:10 -0400 Subject: [PATCH 1/2] 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 --- {docs/adrs => adrs}/.gitkeep | 0 .../0001-record-architecture-decisions.md | 0 .../0002-uds-core-functional-layers.md | 0 docs/application-baseline.md | 26 ---- docs/configuration/_index.md | 5 - docs/configuration/istio/_index.md | 5 - docs/deployment/_index.md | 5 - docs/deployment/uds-deploy.md | 121 ------------------ docs/development/_index.md | 5 - .../UDS Core}/distribution-support.md | 10 +- .../{deployment => reference/UDS Core}/dns.md | 0 .../flavor-specific-development-notes.md} | 2 - .../UDS Core/overview.md} | 9 +- .../UDS Core}/prerequisites.md | 4 - .../configuration}/ingress.md | 18 ++- .../configuration/pepr-policies.md | 2 - .../resource-configuration-and-ha.md | 2 - .../uds-configure-policy-exemptions.md | 2 - .../configuration/uds-monitoring-metrics.md | 6 +- .../configuration/uds-operator.md | 6 +- .../configuration/uds-user-groups.md | 6 +- docs/{ => reference}/deployment/flavors.md | 10 +- 22 files changed, 25 insertions(+), 219 deletions(-) rename {docs/adrs => adrs}/.gitkeep (100%) rename {docs/adrs => adrs}/0001-record-architecture-decisions.md (100%) rename {docs/adrs => adrs}/0002-uds-core-functional-layers.md (100%) delete mode 100644 docs/application-baseline.md delete mode 100644 docs/configuration/_index.md delete mode 100644 docs/configuration/istio/_index.md delete mode 100644 docs/deployment/_index.md delete mode 100644 docs/deployment/uds-deploy.md delete mode 100644 docs/development/_index.md rename docs/{deployment => reference/UDS Core}/distribution-support.md (70%) rename docs/{deployment => reference/UDS Core}/dns.md (100%) rename docs/{development/flavor-specific-dev.md => reference/UDS Core/flavor-specific-development-notes.md} (98%) rename docs/{_index.md => reference/UDS Core/overview.md} (96%) mode change 100755 => 100644 rename docs/{deployment => reference/UDS Core}/prerequisites.md (99%) rename docs/{configuration/istio => reference/configuration}/ingress.md (98%) rename docs/{ => reference}/configuration/pepr-policies.md (99%) rename docs/{ => reference}/configuration/resource-configuration-and-ha.md (99%) rename docs/{ => reference}/configuration/uds-configure-policy-exemptions.md (98%) rename docs/{ => reference}/configuration/uds-monitoring-metrics.md (99%) rename docs/{ => reference}/configuration/uds-operator.md (99%) rename docs/{ => reference}/configuration/uds-user-groups.md (97%) rename docs/{ => reference}/deployment/flavors.md (94%) diff --git a/docs/adrs/.gitkeep b/adrs/.gitkeep similarity index 100% rename from docs/adrs/.gitkeep rename to adrs/.gitkeep diff --git a/docs/adrs/0001-record-architecture-decisions.md b/adrs/0001-record-architecture-decisions.md similarity index 100% rename from docs/adrs/0001-record-architecture-decisions.md rename to adrs/0001-record-architecture-decisions.md diff --git a/docs/adrs/0002-uds-core-functional-layers.md b/adrs/0002-uds-core-functional-layers.md similarity index 100% rename from docs/adrs/0002-uds-core-functional-layers.md rename to adrs/0002-uds-core-functional-layers.md diff --git a/docs/application-baseline.md b/docs/application-baseline.md deleted file mode 100644 index 7eec1c580..000000000 --- a/docs/application-baseline.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -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](https://istio.io/):** A powerful service mesh that provides traffic management, load balancing, security, and observability features. | -| **Monitoring** | **[Metrics Server](https://kubernetes-sigs.github.io/metrics-server/):** Provides container resource utilization metrics API for Kubernetes clusters. Metrics server is an optional (non-default) component since most Kubernetes distros provide it by default.

**[Prometheus](https://prometheus.io/):** Scrapes Metrics Server API and application metrics and stores the data in a time-series database for insights into application health and performance.

**[Grafana](https://grafana.com/grafana/):** Provides visualization and alerting capabilities based on Prometheus's time-series database of metrics. | -| **Logging** | **[Vector](https://vector.dev/):** A companion agent that efficiently gathers and sends container logs to Loki and other storage locations (S3, SIEM tools, etc), simplifying log monitoring, troubleshooting, and compliance auditing, enhancing the overall observability of the mission environment.

**[Loki](https://grafana.com/docs/loki/latest/):** A log aggregation system that allows users to store, search, and analyze logs across their applications. | -| **Security and Compliance** | **[NeuVector](https://open-docs.neuvector.com/):** Offers container-native security, protecting applications against threats and vulnerabilities.

**[Pepr](https://pepr.dev/):** UDS policy engine and operator for enhanced security and compliance.| -| **Identity and Access Management** | **[Keycloak](https://www.keycloak.org/):** 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](https://velero.io/):** Provides backup and restore capabilities for Kubernetes clusters, ensuring data protection and disaster recovery.| -| **Authorization** | **[AuthService](https://github.com/istio-ecosystem/authservice):** Offers centralized authorization services, managing access control and permissions within the Istio mesh. AuthService plays a supporting role to Keycloak as it handles part of the OIDC redirect flow.| -| **Frontend Views & Insights** | **[UDS Runtime](https://github.com/defenseunicorns/uds-runtime)**: UDS Runtime is an optional component in Core that provides the frontend for all things UDS, providing views and insights into your UDS cluster. | diff --git a/docs/configuration/_index.md b/docs/configuration/_index.md deleted file mode 100644 index 1d8ab0844..000000000 --- a/docs/configuration/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Configure UDS Core -type: docs -weight: 3 ---- diff --git a/docs/configuration/istio/_index.md b/docs/configuration/istio/_index.md deleted file mode 100644 index 6872802db..000000000 --- a/docs/configuration/istio/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Istio Configuration for UDS Core -type: docs -weight: 5 ---- diff --git a/docs/deployment/_index.md b/docs/deployment/_index.md deleted file mode 100644 index 9cbb18a82..000000000 --- a/docs/deployment/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Deploying UDS Core -type: docs -weight: 2 ---- diff --git a/docs/deployment/uds-deploy.md b/docs/deployment/uds-deploy.md deleted file mode 100644 index 90b05291e..000000000 --- a/docs/deployment/uds-deploy.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Deploy UDS Core -type: docs -weight: 3 ---- - -## Prerequisites - -Please ensure that the following prerequisites are on your machine prior to deploying UDS Core: - -- [Docker](https://formulae.brew.sh/formula/docker#default), or as an open source alternative, you can use [Colima](https://formulae.brew.sh/formula/colima#default). - - If using Colima, please declare the following resources after installing: - -```git -colima start --cpu 7 --memory 14 --disk 50 -``` - -- [K3d](https://formulae.brew.sh/formula/k3d#default) for development and test environments or a [CNCF Certified Kubernetes Cluster](https://www.cncf.io/training/certification/software-conformance/#logos) if deploying to production environments. -- Dynamic [load-balancer](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer) provisioning such as [MetalLB](https://metallb.universe.tf/). -- Object storage of your choosing such as [Minio](https://min.io/product/kubernetes) or [S3](https://aws.amazon.com/s3/). - -## UDS Bundles - -UDS Core provides published [bundles](https://uds.defenseunicorns.com/bundles/) that serve multiple purposes: you can utilize them for experimenting with UDS Core or for UDS Package development when you only require specific components of UDS Core. These bundles leverage [UDS K3d](https://github.com/defenseunicorns/uds-k3d) to establish a local k3d cluster. - -UDS Bundles deployed for development and testing purposes are comprised of a shared configuration that equips users with essential tools, emulating a development environment for convenience. If deploying to a production environment, users have the ability to modify variables and configurations to best fit specific mission needs by creating their own bundle. - -{{% alert-note %}} -These UDS Bundles are designed specifically for development and testing environments and are *not intended for production use*. Additionally, they serve as examples for creating customized bundles. -{{% /alert-note %}} - -## Quickstart: Development and Test Environments - -**Step 1: Install the [UDS CLI](https://uds.defenseunicorns.com/cli/)** - -It is recommended to update to the latest version, all releases can be found in the [UDS CLI GitHub repository](https://github.com/defenseunicorns/uds-cli/releases). - -```git -brew tap defenseunicorns/tap && brew install uds -``` - -**Step 2: Deploy the UDS Bundle** - -The UDS Bundle being deployed in this example is the [`k3d-core-demo`](https://github.com/defenseunicorns/uds-core/blob/main/bundles/k3d-standard/README.md) bundle which creates a local k3d cluster with UDS Core installed. - -```cli -uds deploy k3d-core-demo:0.20.0 - -# deploy this bundle? -y -``` - -For additional information on UDS Bundles, please see the [UDS Bundles documentation.](https://uds.defenseunicorns.com/bundles/) - -**Optional:** - -Use the following command to visualize resources in the cluster via [k9s:](https://k9scli.io/) - -```git -uds zarf tools monitor -``` - -**Step 3: Clean Up** - -Use the following command to tear down the k3d cluster: - -```git -k3d cluster delete uds -``` - -If you opted to use Colima, use the following command to tear down the virtual machine that the cluster was running on: - -```git -colima delete -f -``` - -## UDS Bundle Development - -In addition to the demo bundle, there is also a [`k3d-slim-dev bundle`](https://github.com/defenseunicorns/uds-core/tree/main/bundles/k3d-istio) designed specifically for working with UDS Core with *only* Istio, Keycloak, and Pepr installed. To use it, execute the following command: - -```cli -uds deploy k3d-core-slim-dev:0.20.0 -``` - -## Developing UDS Core - -UDS Core development leverages the `uds zarf dev deploy` command. To simplify the setup process, a dedicated UDS Task is available. Please ensure you have [NodeJS](https://nodejs.org/en/download/) version 20 or later installed before proceeding. - -Below is an example of the workflow developing the [metrics-server package](https://github.com/defenseunicorns/uds-core/tree/main/src/metrics-server): - -```cli -# Create the dev environment -uds run dev-setup - -# If developing the Pepr module: -npx pepr dev - -# If not developing the Pepr module (can be run multiple times): -npx pepr deploy - -# Deploy the package (can be run multiple times) -uds run dev-deploy --set PKG=metrics-server -``` - -## Testing UDS Core - -You can perform a complete test of UDS Core by running the following command: - -```cli -uds run test-uds-core -``` - -This will create a local k3d cluster, install UDS Core, and run a series of tests against it, the same tests that are run in CI. If you want to run the tests against a specific core layer, you can use the `LAYER` task variable. The following example runs the tests against the identity-authorization layer: - -```cli -uds run test-single-layer --set LAYER=identity-authorization -``` - -{{% alert-note %}} -You can specify the `--set FLAVOR=registry1` flag to test using Iron Bank images instead of the upstream images. -{{% /alert-note %}} diff --git a/docs/development/_index.md b/docs/development/_index.md deleted file mode 100644 index d49d49f68..000000000 --- a/docs/development/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: UDS Core Development -type: docs -weight: 4 ---- diff --git a/docs/deployment/distribution-support.md b/docs/reference/UDS Core/distribution-support.md similarity index 70% rename from docs/deployment/distribution-support.md rename to docs/reference/UDS Core/distribution-support.md index 268366559..89afcf8e9 100644 --- a/docs/deployment/distribution-support.md +++ b/docs/reference/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 b/docs/reference/UDS Core/dns.md similarity index 100% rename from docs/deployment/dns.md rename to docs/reference/UDS Core/dns.md diff --git a/docs/development/flavor-specific-dev.md b/docs/reference/UDS Core/flavor-specific-development-notes.md similarity index 98% rename from docs/development/flavor-specific-dev.md rename to docs/reference/UDS Core/flavor-specific-development-notes.md index 8928a949d..7a576c5b8 100644 --- a/docs/development/flavor-specific-dev.md +++ b/docs/reference/UDS 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 b/docs/reference/UDS Core/overview.md old mode 100755 new mode 100644 similarity index 96% rename from docs/_index.md rename to docs/reference/UDS Core/overview.md index 3d7fb94d4..94c3fa810 --- a/docs/_index.md +++ b/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 b/docs/reference/UDS Core/prerequisites.md similarity index 99% rename from docs/deployment/prerequisites.md rename to docs/reference/UDS Core/prerequisites.md index ddc8e038e..24a678f58 100644 --- a/docs/deployment/prerequisites.md +++ b/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 b/docs/reference/configuration/ingress.md similarity index 98% rename from docs/configuration/istio/ingress.md rename to docs/reference/configuration/ingress.md index e94cceec5..38b1e16ea 100644 --- a/docs/configuration/istio/ingress.md +++ b/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,7 +44,7 @@ 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 @@ -54,6 +52,9 @@ packages: 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,7 +82,7 @@ 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 @@ -92,6 +90,6 @@ variables: 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 b/docs/reference/configuration/pepr-policies.md similarity index 99% rename from docs/configuration/pepr-policies.md rename to docs/reference/configuration/pepr-policies.md index fa05a3557..f2cf82b77 100644 --- a/docs/configuration/pepr-policies.md +++ b/docs/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/docs/configuration/resource-configuration-and-ha.md b/docs/reference/configuration/resource-configuration-and-ha.md similarity index 99% rename from docs/configuration/resource-configuration-and-ha.md rename to docs/reference/configuration/resource-configuration-and-ha.md index 9680a6009..1993862c9 100644 --- a/docs/configuration/resource-configuration-and-ha.md +++ b/docs/reference/configuration/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/docs/configuration/uds-configure-policy-exemptions.md b/docs/reference/configuration/uds-configure-policy-exemptions.md similarity index 98% rename from docs/configuration/uds-configure-policy-exemptions.md rename to docs/reference/configuration/uds-configure-policy-exemptions.md index 2e405cbc1..c68b35b1e 100644 --- a/docs/configuration/uds-configure-policy-exemptions.md +++ b/docs/reference/configuration/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 b/docs/reference/configuration/uds-monitoring-metrics.md similarity index 99% rename from docs/configuration/uds-monitoring-metrics.md rename to docs/reference/configuration/uds-monitoring-metrics.md index 909d5ad5f..c5ef0da68 100644 --- a/docs/configuration/uds-monitoring-metrics.md +++ b/docs/reference/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 b/docs/reference/configuration/uds-operator.md similarity index 99% rename from docs/configuration/uds-operator.md rename to docs/reference/configuration/uds-operator.md index 29271d0d5..927af5cef 100644 --- a/docs/configuration/uds-operator.md +++ b/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 b/docs/reference/configuration/uds-user-groups.md similarity index 97% rename from docs/configuration/uds-user-groups.md rename to docs/reference/configuration/uds-user-groups.md index a654e551a..bcce50fdd 100644 --- a/docs/configuration/uds-user-groups.md +++ b/docs/reference/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 ) diff --git a/docs/deployment/flavors.md b/docs/reference/deployment/flavors.md similarity index 94% rename from docs/deployment/flavors.md rename to docs/reference/deployment/flavors.md index 680a2872e..26349aa16 100644 --- a/docs/deployment/flavors.md +++ b/docs/reference/deployment/flavors.md @@ -1,14 +1,12 @@ --- title: Published Flavors -type: docs -weight: 2 --- UDS Core is published with multiple variations (Zarf flavors). Each flavor uses a separate source registry for the images. Each flavor is used as the suffix on the OCI tags for packages. For production use cases we recommend the `registry1` or `unicorn` flavors as these images tend to be more secure than their `upstream` counterparts. -{{% alert-note %}} +:::note Demo and dev bundles (`k3d-core-demo` and `k3d-core-slim-dev`) are only published from the upstream flavor. -{{% /alert-note %}} +::: ### Flavors @@ -18,6 +16,6 @@ Demo and dev bundles (`k3d-core-demo` and `k3d-core-slim-dev`) are only publishe | `upstream` | `ghcr.io/defenseunicorns/packages/uds` | Various sources, typically DockerHub/GHCR/Quay, these are the default images used by helm charts | | **ALPHA** `unicorn` | `ghcr.io/defenseunicorns/packages/private/uds` | Industry best images designed with security and minimalism in mind | -{{% alert-note %}} +:::note The `unicorn` flavored packages are only available in a private repository. These packages are available for all members of the Defense Unicorns organization/company, if you are outside the organization [contact us](https://www.defenseunicorns.com/contactus) if you are interested in using this flavor for your mission. -{{% /alert-note %}} +::: From 70d6b1b943e0e9fc3a36fc7a7600afa0e3f2b511 Mon Sep 17 00:00:00 2001 From: Micah Nagel Date: Fri, 11 Oct 2024 14:24:41 -0600 Subject: [PATCH 2/2] chore: handle upgrade path for functional layers, add doc for usage (#896) ## Description Changes included: 1. Functional layers upgrade was not successful when I tested initially. There were ownership issues with the `manifests` we use for istio. To resolve that problem I moved the manifests into a chart and added an action to update the ownership before the upgrade. I also removed the pepr action that we have had for several releases since it was needed as a one-time upgrade step (similar to this one). 2. Added a lightweight doc on the usage of functional layers with a very brief explanation and warning as well as a full example of a bundle pulling in the layers. 3. A few misc link fixes and other things to follow the astro docs switch. ## Related Issue Fixes https://github.com/defenseunicorns/uds-core/issues/868 Fixes https://github.com/defenseunicorns/uds-core/issues/900 ## Type of change - [x] 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 - [x] Test, docs, adr added or updated as needed - [x] [Contributor Guide](https://github.com/defenseunicorns/uds-template-capability/blob/main/CONTRIBUTING.md) followed --------- Co-authored-by: Noah <40781376+noahpb@users.noreply.github.com> --- README.md | 2 +- docs/reference/UDS Core/dns.md | 17 +++---- docs/reference/UDS Core/functional-layers.md | 51 +++++++++++++++++++ docs/reference/UDS Core/prerequisites.md | 4 +- docs/reference/configuration/ingress.md | 6 +-- docs/reference/configuration/uds-operator.md | 2 +- src/istio/common/chart/.helmignore | 23 +++++++++ src/istio/common/chart/Chart.yaml | 19 +++++++ .../templates}/envoy-filters.yaml | 0 .../templates}/peer-authentication.yaml | 0 .../templates}/pepr-istio-config.yaml | 0 src/istio/common/chart/values.yaml | 1 + src/istio/common/zarf.yaml | 17 +++++-- src/pepr/zarf.yaml | 20 -------- 14 files changed, 122 insertions(+), 40 deletions(-) create mode 100644 docs/reference/UDS Core/functional-layers.md create mode 100644 src/istio/common/chart/.helmignore create mode 100644 src/istio/common/chart/Chart.yaml rename src/istio/common/{manifests => chart/templates}/envoy-filters.yaml (100%) rename src/istio/common/{manifests => chart/templates}/peer-authentication.yaml (100%) rename src/istio/common/{manifests => chart/templates}/pepr-istio-config.yaml (100%) create mode 100644 src/istio/common/chart/values.yaml diff --git a/README.md b/README.md index c8205e9ce..506d7ab71 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Unicorn Delivery Service - Core (UDS Core) -## [UDS Core Docs](https://uds.defenseunicorns.com/core/) +## [UDS Core Overview](https://uds.defenseunicorns.com/reference/uds-core/overview/) UDS Core establishes a secure baseline for cloud-native systems and ships with compliance documentation and first-class support for airgap/egress-limited systems. Based on the work of [Platform One](https://p1.dso.mil), UDS Core expands on the security posture of [Big Bang](https://repo1.dso.mil/big-bang/bigbang) while providing advanced automation with the [UDS Operator](./src/pepr/operator/README.md) and [UDS Policy Engine](./src/pepr/policies/README.md). UDS Core is a collection of several individual applications combined into a single [Zarf](https://zarf.dev) package and we recommend using [UDS CLI](https://github.com/defenseunicorns/uds-cli?tab=readme-ov-file#install) to deploy it as a [UDS Bundle](#using-uds-core-in-production). diff --git a/docs/reference/UDS Core/dns.md b/docs/reference/UDS Core/dns.md index b1dcef9bc..9d493e6bd 100644 --- a/docs/reference/UDS Core/dns.md +++ b/docs/reference/UDS Core/dns.md @@ -1,24 +1,23 @@ --- title: DNS Configuration -type: docs -weight: 2 --- -UDS Core deploys two Gateways by default - a Tenant Gateway for end-user applications and an Admin Gateway for administrative applications. You can read more about Istio configuration in UDS Core [here](https://uds.defenseunicorns.com/core/configuration/istio/ingress/). This section covers how to configure DNS for these Gateways. +UDS Core deploys two Gateways by default - a Tenant Gateway for end-user applications and an Admin Gateway for administrative applications. You can read more about Istio configuration in UDS Core [here](https://uds.defenseunicorns.com/reference/configuration/ingress/). This section covers how to configure DNS for these Gateways. ### Domain Configuration Each Gateway is associated to a wildcard DNS entry that is derived from the `DOMAIN` [variable](https://github.com/defenseunicorns/uds-core/blob/e624d73f79bd6739b6808fbdbf5ca75ebb7c1d3c/src/istio/zarf.yaml#L8) in the UDS Core Istio package. When deploying UDS Core, you can expect two Gateways to be created that match the following domain names: - `*.` / Tenant Gateway - `*.admin.` / Admin Gateway -{{% alert-note %}} -The default value for `DOMAIN` is `uds.dev`, which is intended for development purposes only. For non-development purposes, you should override this value by specifying a value for `domain` in your `uds-config.yaml`. You can find instructions on how to do so [here](https://uds.defenseunicorns.com/core/configuration/istio/ingress/#configure-domain-name-and-tls-for-istio-gateways). -{{% /alert-note %}} +:::note +The default value for `DOMAIN` is `uds.dev`, which is intended for development purposes only. For non-development purposes, you should override this value by specifying a value for `domain` in your `uds-config.yaml`. You can find instructions on how to do so [here](https://uds.defenseunicorns.com/reference/configuration/ingress/#configure-domain-name-and-tls-for-istio-gateways). +::: ### Bundle Configuration -{{% alert-note %}} + +:::note UDS Core does not include any cloud provider specific configuration by default. Additional overrides are required to deploy UDS Core on a given provider. This section will refer to AWS, but values can be substituted as needed for other providers. -{{% /alert-note %}} +::: The Admin and Tenant Gateways will be each be bound to an external Load Balancer that is exposed on TCP ports 80 and 443 by default. The Admin Gateway should be configured to use an internal facing Load Balancer and the Tenant Gateway should be configured to use an external facing Load Balancer. Below is an example of overrides that would accomplish this: ```yaml @@ -71,4 +70,4 @@ istio-admin-gateway admin-ingressgateway Loa istio-tenant-gateway tenant-ingressgateway LoadBalancer 10.43.47.182 k8s-istioten-tenant...elb.us-east-1.amazonaws.com 15021:31222/TCP,80:30456/TCP,443:32508/TCP 1h ``` -From here, you can register your domain and/or create DNS records for your environment that point to the appropriate Gateways/Load Balancers. Refer to your DNS provider's documentation. \ No newline at end of file +From here, you can register your domain and/or create DNS records for your environment that point to the appropriate Gateways/Load Balancers. Refer to your DNS provider's documentation. diff --git a/docs/reference/UDS Core/functional-layers.md b/docs/reference/UDS Core/functional-layers.md new file mode 100644 index 000000000..7ba6a8f3a --- /dev/null +++ b/docs/reference/UDS Core/functional-layers.md @@ -0,0 +1,51 @@ +--- +title: Functional Layers +--- + +## Background + +Context on the inclusion of "functional layers" can be viewed in our [ADR](https://github.com/defenseunicorns/uds-core/blob/main/docs/adrs/0002-uds-core-functional-layers.md). In short, UDS Core publishes smaller Zarf packages that contain subsets of core's capabilities, grouped by their function (such as monitoring, logging, backup/restore, etc) to allow more flexibility in deployment. This helps to support resource constrained environments (edge deployments) and other situations where an environment has different needs than the default core stack. + +Each layer is published as an individual OCI Zarf package. Package sources can be viewed under the [`packages` directory](https://github.com/defenseunicorns/uds-core/tree/main/packages), with each folder containing a readme detailing the contents and any dependencies. All layers assume the requirement of the base layer which provides Istio, the UDS Operator, and UDS Policy Engine. + +:::caution +By removing pieces of core from your deployment you may affect your security and compliance posture as well as reduce functionality of the stack. Deploying core using these layers should be the exception in most cases and only done after carefully weighing needs for your environment. +::: + +## Example Usage + +Functional layers are designed to be combined into a UDS bundle for deployment. The example below shows all layers in the correct order. Keep in mind that 'base' must always be the first layer, and any other layers should follow based on their dependency order. When building your bundle, you can skip layers that don't fit your deployment needs and apply overrides to individual layers as needed. Ensure all layers are using the same version for compatibility. + +```yaml +kind: UDSBundle +metadata: + name: functional-layer-core-bundle + description: An example bundle for deploying all of core using functional layers + version: "0.1.0" + +packages: + - name: core-base + repository: ghcr.io/defenseunicorns/packages/uds/core-base + ref: 0.29.0-upstream + - name: core-identity-authorization + repository: ghcr.io/defenseunicorns/packages/uds/core-identity-authorization + ref: 0.29.0-upstream + - name: core-metrics-server + repository: ghcr.io/defenseunicorns/packages/uds/core-metrics-server + ref: 0.29.0-upstream + - name: core-runtime-security + repository: ghcr.io/defenseunicorns/packages/uds/core-runtime-security + ref: 0.29.0-upstream + - name: core-logging + repository: ghcr.io/defenseunicorns/packages/uds/core-logging + ref: 0.29.0-upstream + - name: core-monitoring + repository: ghcr.io/defenseunicorns/packages/uds/core-monitoring + ref: 0.29.0-upstream + - name: core-ui + repository: ghcr.io/defenseunicorns/packages/uds/core-ui + ref: 0.29.0-upstream + - name: core-backup-restore + repository: ghcr.io/defenseunicorns/packages/uds/core-backup-restore + ref: 0.29.0-upstream +``` diff --git a/docs/reference/UDS Core/prerequisites.md b/docs/reference/UDS Core/prerequisites.md index 24a678f58..14d8b7fcf 100644 --- a/docs/reference/UDS Core/prerequisites.md +++ b/docs/reference/UDS Core/prerequisites.md @@ -1,5 +1,7 @@ --- -title: UDS Core Prerequisites +title: Prerequisites +sidebar: + order: 2 --- `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. diff --git a/docs/reference/configuration/ingress.md b/docs/reference/configuration/ingress.md index 38b1e16ea..5015bc928 100644 --- a/docs/reference/configuration/ingress.md +++ b/docs/reference/configuration/ingress.md @@ -36,7 +36,7 @@ packages: By default, the UDS Core Istio Gateways are set up to use the `uds.dev` domain and have a valid TLS certificate packaged. You will want to change the domain name for your environment and provide a valid TLS certificate for this domain. -You can set the TLS certs via overrides in a [UDS Bundle](https://uds.defenseunicorns.com/bundles/) (see below). UDS Core Istio Gateways default to only supporting TLS v1.3, but this can also be overridden per gateway if clients use TLS 1.2 (as seen in the tenant gateway example `value` below). +You can set the TLS certs via overrides in a [UDS Bundle](https://uds.defenseunicorns.com/structure/bundles/) (see below). UDS Core Istio Gateways default to only supporting TLS v1.3, but this can also be overridden per gateway if clients use TLS 1.2 (as seen in the tenant gateway example `value` below). ```yaml kind: UDSBundle @@ -75,7 +75,7 @@ packages: You can then either use environment variables (`UDS_ADMIN_TLS_CERT`, `UDS_ADMIN_TLS_KEY`, `UDS_TENANT_TLS_CERT`, and `UDS_TENANT_TLS_KEY`) or a config file to configure the certs for each gateway. These values should be base64 encoded strings of the TLS certificate and key for the admin and tenant gateways respectively. -Domain should be set via your [uds-config](https://uds.defenseunicorns.com/cli/quickstart-and-usage/#variables-and-configuration) file using the shared key to override the Zarf Domain Variable (see example `uds-config.yaml` below). +Domain should be set via your [uds-config](https://uds.defenseunicorns.com/reference/cli/quickstart-and-usage/#variables-and-configuration) file using the shared key to override the Zarf Domain Variable (see example `uds-config.yaml` below). ```yaml shared: @@ -91,5 +91,5 @@ variables: ``` :::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). +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/reference/configuration/uds-operator/#trusted-certificate-authority). ::: diff --git a/docs/reference/configuration/uds-operator.md b/docs/reference/configuration/uds-operator.md index 927af5cef..5593a91ee 100644 --- a/docs/reference/configuration/uds-operator.md +++ b/docs/reference/configuration/uds-operator.md @@ -181,7 +181,7 @@ variables: CA_CERT: ``` -See [configuring Istio Ingress](https://uds.defenseunicorns.com/core/configuration/istio/ingress/#configure-domain-name-and-tls-for-istio-gateways) for the relevant documentation on configuring ingress certificates. +See [configuring Istio Ingress](https://uds.defenseunicorns.com/reference/configuration/ingress/#configure-domain-name-and-tls-for-istio-gateways) for the relevant documentation on configuring ingress certificates. ### Creating a UDS Package with a Device Flow client diff --git a/src/istio/common/chart/.helmignore b/src/istio/common/chart/.helmignore new file mode 100644 index 000000000..0e8a0eb36 --- /dev/null +++ b/src/istio/common/chart/.helmignore @@ -0,0 +1,23 @@ +# Patterns to ignore when building packages. +# This supports shell glob matching, relative path matching, and +# negation (prefixed with !). Only one pattern per line. +.DS_Store +# Common VCS dirs +.git/ +.gitignore +.bzr/ +.bzrignore +.hg/ +.hgignore +.svn/ +# Common backup files +*.swp +*.bak +*.tmp +*.orig +*~ +# Various IDEs +.project +.idea/ +*.tmproj +.vscode/ diff --git a/src/istio/common/chart/Chart.yaml b/src/istio/common/chart/Chart.yaml new file mode 100644 index 000000000..2936bb951 --- /dev/null +++ b/src/istio/common/chart/Chart.yaml @@ -0,0 +1,19 @@ +# SPDX-License-Identifier: AGPL-3.0-or-later OR Commercial +apiVersion: v2 +name: uds-global-istio-config +description: Global Istio configuration for UDS + +# A chart can be either an 'application' or a 'library' chart. +# +# Application charts are a collection of templates that can be packaged into versioned archives +# to be deployed. +# +# Library charts provide useful utilities or functions for the chart developer. They're included as +# a dependency of application charts to inject those utilities and functions into the rendering +# pipeline. Library charts do not define any templates and therefore cannot be deployed. +type: application + +# This is the chart version. This version number should be incremented each time you make changes +# to the chart and its templates, including the app version. +# Versions are expected to follow Semantic Versioning (https://semver.org/) +version: 0.1.0 diff --git a/src/istio/common/manifests/envoy-filters.yaml b/src/istio/common/chart/templates/envoy-filters.yaml similarity index 100% rename from src/istio/common/manifests/envoy-filters.yaml rename to src/istio/common/chart/templates/envoy-filters.yaml diff --git a/src/istio/common/manifests/peer-authentication.yaml b/src/istio/common/chart/templates/peer-authentication.yaml similarity index 100% rename from src/istio/common/manifests/peer-authentication.yaml rename to src/istio/common/chart/templates/peer-authentication.yaml diff --git a/src/istio/common/manifests/pepr-istio-config.yaml b/src/istio/common/chart/templates/pepr-istio-config.yaml similarity index 100% rename from src/istio/common/manifests/pepr-istio-config.yaml rename to src/istio/common/chart/templates/pepr-istio-config.yaml diff --git a/src/istio/common/chart/values.yaml b/src/istio/common/chart/values.yaml new file mode 100644 index 000000000..c56503481 --- /dev/null +++ b/src/istio/common/chart/values.yaml @@ -0,0 +1 @@ +# SPDX-License-Identifier: AGPL-3.0-or-later OR Commercial diff --git a/src/istio/common/zarf.yaml b/src/istio/common/zarf.yaml index 0c7ae9279..0107b58ad 100644 --- a/src/istio/common/zarf.yaml +++ b/src/istio/common/zarf.yaml @@ -19,15 +19,22 @@ components: namespace: istio-system valuesFiles: - "../values/values.yaml" - manifests: - name: uds-global-istio-config namespace: istio-system - files: - - "manifests/envoy-filters.yaml" - - "manifests/peer-authentication.yaml" - - "manifests/pepr-istio-config.yaml" + version: 0.1.0 + localPath: chart actions: onDeploy: + before: + - description: "Fix helm ownership if necessary for clean helm upgrade" + mute: true + cmd: | + ./zarf tools kubectl annotate EnvoyFilter misdirected-request -n istio-system meta.helm.sh/release-name=uds-global-istio-config --overwrite || true + ./zarf tools kubectl annotate EnvoyFilter remove-server-header -n istio-system meta.helm.sh/release-name=uds-global-istio-config --overwrite || true + ./zarf tools kubectl annotate PeerAuthentication default-istio-system -n istio-system meta.helm.sh/release-name=uds-global-istio-config --overwrite || true + ./zarf tools kubectl annotate PeerAuthentication permissive-pepr-webhook -n pepr-system meta.helm.sh/release-name=uds-global-istio-config --overwrite || true + ./zarf tools kubectl annotate PeerAuthentication permissive-pepr-webhook-watcher -n pepr-system meta.helm.sh/release-name=uds-global-istio-config --overwrite || true after: - description: "Ensure istio-injection is enabled for Pepr" + mute: true cmd: "./zarf tools kubectl label namespace pepr-system istio-injection=enabled --overwrite" diff --git a/src/pepr/zarf.yaml b/src/pepr/zarf.yaml index ea1a8925b..2f7e22ba6 100644 --- a/src/pepr/zarf.yaml +++ b/src/pepr/zarf.yaml @@ -46,23 +46,3 @@ components: - name: module valuesFiles: - values.yaml - actions: - onDeploy: - before: - - mute: true - description: "Update helm ownership for Pepr resources if necessary during the upgrade" - cmd: | - ./zarf tools kubectl annotate secret -n pepr-system pepr-uds-core-api-token meta.helm.sh/release-name=module --overwrite || true - ./zarf tools kubectl annotate secret -n pepr-system pepr-uds-core-module meta.helm.sh/release-name=module --overwrite || true - ./zarf tools kubectl annotate secret -n pepr-system pepr-uds-core-tls meta.helm.sh/release-name=module --overwrite || true - ./zarf tools kubectl annotate serviceaccount -n pepr-system pepr-uds-core meta.helm.sh/release-name=module --overwrite || true - ./zarf tools kubectl annotate clusterrolebinding pepr-uds-core meta.helm.sh/release-name=module --overwrite || true - ./zarf tools kubectl annotate clusterrole pepr-uds-core meta.helm.sh/release-name=module --overwrite || true - ./zarf tools kubectl annotate role -n pepr-system pepr-uds-core-store meta.helm.sh/release-name=module --overwrite || true - ./zarf tools kubectl annotate rolebinding -n pepr-system pepr-uds-core-store meta.helm.sh/release-name=module --overwrite || true - ./zarf tools kubectl annotate service -n pepr-system pepr-uds-core meta.helm.sh/release-name=module --overwrite || true - ./zarf tools kubectl annotate service -n pepr-system pepr-uds-core-watcher meta.helm.sh/release-name=module --overwrite || true - ./zarf tools kubectl annotate deployment -n pepr-system pepr-uds-core meta.helm.sh/release-name=module --overwrite || true - ./zarf tools kubectl annotate deployment -n pepr-system pepr-uds-core-watcher meta.helm.sh/release-name=module --overwrite || true - ./zarf tools kubectl annotate mutatingwebhookconfiguration -n pepr-system pepr-uds-core meta.helm.sh/release-name=module --overwrite || true - ./zarf tools kubectl annotate validatingwebhookconfiguration -n pepr-system pepr-uds-core meta.helm.sh/release-name=module --overwrite || true