From b1a6db926bcfd455615c7cf2c7b73929f3af6171 Mon Sep 17 00:00:00 2001 From: Chance <139784371+UnicornChance@users.noreply.github.com> Date: Fri, 17 May 2024 12:18:26 -0600 Subject: [PATCH] feat: uds core docs (#414) ## Description Integrated docs between `uds` and other repos. `uds-core` is the initial repo to be integrated. The module repo's need to add a go.mod file to their `docs` directory which is then pulled in by the `uds` repo to add the docs to the hugo site. The module repo's need to pr changes before the `uds` repo's pr can be pushed in due to failing CI runs because the main branch of the module repo's doesn't have the go.mod file present. I attempted copy and paste the doc files from `uds` with minimal changes, only changes would be links needing to reference urls instead of static local files. Hopefully the only real changes are the: * go.mod file * frontmatter addition to doc files * syntax changes for links and alert messages in docs # Will let @Jessy-Morris take the first crack at reviewing this since this is her domain! # # How to review 1. checkout the [core-docs-import](https://github.com/defenseunicorns/uds/tree/core-docs-import) branch on `uds` 2. run `npm run start` 3. open `localhost:1313` in the browser and there should be `UDS Core` tab to view the docs in this uds-core branch. ## Type of change - [ ] Bug fix (non-breaking change which fixes an issue) - [x] New feature (non-breaking change which adds functionality) - [ ] Other (security config, docs update, etc) ## Checklist before merging - [x] Test, docs, adr added or updated as needed - [x] [Contributor Guide Steps](https://github.com/defenseunicorns/uds-template-capability/blob/main/CONTRIBUTING.md)(https://github.com/defenseunicorns/uds-template-capability/blob/main/CONTRIBUTING.md#submitting-a-pull-request) followed --------- Co-authored-by: Rob Ferguson --- docs/_index.md | 30 +++ docs/application-baseline.md | 25 +++ docs/configuration/_index.md | 5 + .../uds-configure-policy-exemptions.md} | 9 +- .../uds-monitoring-metrics.md} | 6 +- docs/configuration/uds-operator.md | 205 ++++++++++++++++++ .../uds-user-groups.md} | 13 +- docs/deployment/_index.md | 5 + docs/deployment/distribution-support.md | 19 ++ docs/deployment/uds-deploy.md | 123 +++++++++++ docs/development/_index.md | 5 + .../uds-development-maintenance.md} | 6 + docs/go.mod | 3 + 13 files changed, 446 insertions(+), 8 deletions(-) create mode 100755 docs/_index.md create mode 100644 docs/application-baseline.md create mode 100644 docs/configuration/_index.md rename docs/{CONFIGURE_POLICY_EXEMPTIONS.md => configuration/uds-configure-policy-exemptions.md} (64%) rename docs/{MONITOR.md => configuration/uds-monitoring-metrics.md} (98%) create mode 100644 docs/configuration/uds-operator.md rename docs/{UDS_CORE_GROUPS.md => configuration/uds-user-groups.md} (84%) create mode 100644 docs/deployment/_index.md create mode 100644 docs/deployment/distribution-support.md create mode 100644 docs/deployment/uds-deploy.md create mode 100644 docs/development/_index.md rename docs/{DEVELOPMENT_MAINTENANCE.md => development/uds-development-maintenance.md} (71%) create mode 100644 docs/go.mod diff --git a/docs/_index.md b/docs/_index.md new file mode 100755 index 000000000..3d7fb94d4 --- /dev/null +++ b/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. diff --git a/docs/application-baseline.md b/docs/application-baseline.md new file mode 100644 index 000000000..c16ea009d --- /dev/null +++ b/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.

**Grafana:** Provides visualization and alerting capabilities for monitoring metrics.

**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.

**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.

**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. | diff --git a/docs/configuration/_index.md b/docs/configuration/_index.md new file mode 100644 index 000000000..1d8ab0844 --- /dev/null +++ b/docs/configuration/_index.md @@ -0,0 +1,5 @@ +--- +title: Configure UDS Core +type: docs +weight: 3 +--- diff --git a/docs/CONFIGURE_POLICY_EXEMPTIONS.md b/docs/configuration/uds-configure-policy-exemptions.md similarity index 64% rename from docs/CONFIGURE_POLICY_EXEMPTIONS.md rename to docs/configuration/uds-configure-policy-exemptions.md index 25c4ec0df..8b062beb8 100644 --- a/docs/CONFIGURE_POLICY_EXEMPTIONS.md +++ b/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. diff --git a/docs/MONITOR.md b/docs/configuration/uds-monitoring-metrics.md similarity index 98% rename from docs/MONITOR.md rename to docs/configuration/uds-monitoring-metrics.md index 0dcf9396c..04f40b6ab 100644 --- a/docs/MONITOR.md +++ b/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. diff --git a/docs/configuration/uds-operator.md b/docs/configuration/uds-operator.md new file mode 100644 index 000000000..f406192b1 --- /dev/null +++ b/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 +``` diff --git a/docs/UDS_CORE_GROUPS.md b/docs/configuration/uds-user-groups.md similarity index 84% rename from docs/UDS_CORE_GROUPS.md rename to docs/configuration/uds-user-groups.md index 34c2579a2..cf7db2466 100644 --- a/docs/UDS_CORE_GROUPS.md +++ b/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 ) diff --git a/docs/deployment/_index.md b/docs/deployment/_index.md new file mode 100644 index 000000000..9cbb18a82 --- /dev/null +++ b/docs/deployment/_index.md @@ -0,0 +1,5 @@ +--- +title: Deploying UDS Core +type: docs +weight: 2 +--- diff --git a/docs/deployment/distribution-support.md b/docs/deployment/distribution-support.md new file mode 100644 index 000000000..9815af70e --- /dev/null +++ b/docs/deployment/distribution-support.md @@ -0,0 +1,19 @@ +--- +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. + +### Understanding Support Levels + +- **Supported:** The Kubernetes distributions listed under this category undergo testing and are officially supported by UDS Core. Users can expect a high level of reliability and compatibility when deploying UDS Core on these distributions. + +- **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 | +| --------------- | ---------------------- | --------------------------------------------------------------------------------------------------------- | +| K3d, 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. | \ No newline at end of file diff --git a/docs/deployment/uds-deploy.md b/docs/deployment/uds-deploy.md new file mode 100644 index 000000000..e230bef54 --- /dev/null +++ b/docs/deployment/uds-deploy.md @@ -0,0 +1,123 @@ +--- +title: Deploy UDS Core +type: docs +weight: 2 +--- + +## 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 6 --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 + +# 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 command initiates the creation of a local k3d cluster, installs UDS Core, and executes a set of tests identical to those performed in CI. If you wish to run tests targeting a specific package, you can utilize the `PKG` environment variable. + +The example below runs tests against the metrics-server package: + +```cli +UDS_PKG=metrics-server uds run test-single-package +``` + +{{% 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 new file mode 100644 index 000000000..d49d49f68 --- /dev/null +++ b/docs/development/_index.md @@ -0,0 +1,5 @@ +--- +title: UDS Core Development +type: docs +weight: 4 +--- diff --git a/docs/DEVELOPMENT_MAINTENANCE.md b/docs/development/uds-development-maintenance.md similarity index 71% rename from docs/DEVELOPMENT_MAINTENANCE.md rename to docs/development/uds-development-maintenance.md index 61650a4a5..cc1364aea 100644 --- a/docs/DEVELOPMENT_MAINTENANCE.md +++ b/docs/development/uds-development-maintenance.md @@ -1,3 +1,9 @@ +--- +title: Development Maintenance +type: docs +weight: 1 +--- + # UDS Bundle [name] ## How to upgrade this bundle diff --git a/docs/go.mod b/docs/go.mod new file mode 100644 index 000000000..d520ac5fd --- /dev/null +++ b/docs/go.mod @@ -0,0 +1,3 @@ +module github.com/defenseunicorns/uds-core/docs + +go 1.20 \ No newline at end of file