/ README.md
README.md
1 # Unicorn Delivery Service - Core (UDS Core) 2 3 [](https://github.com/defenseunicorns/uds-core/releases) 4 [](https://github.com/defenseunicorns/uds-core/tag-and-release.yaml) 5 [](https://api.securityscorecards.dev/projects/github.com/defenseunicorns/uds-core) 6 [](https://www.bestpractices.dev/projects/10959) 7 8 ## [UDS Core Overview](https://uds.defenseunicorns.com/reference/uds-core/overview/) 9 10 UDS Core establishes a secure baseline for cloud-native systems and ships with compliance documentation and first-class support for airgap/egress-limited systems. UDS Core provides 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). 11 12 #### tl;dr - [try it now](#quickstart) 13 14 #### Core Applications 15 16 - [Authservice](https://github.com/istio-ecosystem/authservice) - Authorization 17 - [Grafana](https://grafana.com/oss/grafana/) - Monitoring 18 - [Istio](https://istio.io/) - Service Mesh 19 - [KeyCloak](https://www.keycloak.org/) - Identity & Access Management 20 - [Loki](https://grafana.com/oss/loki/) - Log Aggregation 21 - [Metrics Server](https://github.com/kubernetes-sigs/metrics-server) - Metrics 22 - [Falco](https://falco.org/docs/) - Container Security 23 - [Pepr](https://pepr.dev) - UDS policy engine & operator 24 - [Prometheus Stack](https://github.com/prometheus-operator/kube-prometheus) - Monitoring 25 - [Vector](https://vector.dev/) - Log Aggregation 26 - [Velero](https://velero.io/) - Backup & Restore 27 28 --- 29 30 ### Prerequisites 31 32 - A running container environment for K3D to interact with for dev & test environments 33 - [K3D](https://k3d.io/) v5.7.1 or later for dev & test environments or any [CNCF Certified Kubernetes Cluster](https://www.cncf.io/training/certification/software-conformance/#logos) for production environments. 34 <!-- renovate: datasource=github-tags depName=defenseunicorns/uds-cli versioning=semver --> 35 - [UDS CLI](https://github.com/defenseunicorns/uds-cli?tab=readme-ov-file#install): v0.27.21 or later 36 37 --- 38 39 ### Using UDS Core in Production 40 41 While the UDS Bundles published by this repo can be used for dev and test environments and include a K3d cluster, UDS Core also publishes a UDS Package that is intended to be used in your own UDS Bundle. You can use the [k3d-core-demo bundle](./bundles/k3d-standard/README.md) as an example. 42 43 --- 44 45 ### Quickstart, Dev & Test Environments 46 47 UDS Core publishes bundles you can use for trying out UDS Core or for UDS Package development where you only need part of UDS Core. These bundles leverage [UDS K3d](https://github.com/defenseunicorns/uds-k3d) to create a local k3d cluster with tools installed to emulate a cloud environment. 48 49 > [!NOTE] 50 > These UDS Bundles are intended for dev and test environments and should not be used for production. They also serve as examples to create custom bundles. 51 52 #### Quickstart 53 54 If you want to try out UDS Core, you can use the [k3d-core-demo bundle](./bundles/k3d-standard/README.md) to create a local k3d cluster with UDS Core installed by running the following command: 55 56 <!-- x-release-please-start-version --> 57 58 ```bash 59 uds deploy k3d-core-demo:0.59.0 60 ``` 61 62 <!-- x-release-please-end --> 63 64 #### UDS Package Development 65 66 In addition to the demo bundle, a [k3d-slim-dev bundle](./bundles/k3d-slim-dev/README.md) also exists to work with UDS Core with only Istio, Keycloak & Pepr installed. Run the command below to use it. 67 68 Deploy Istio, Keycloak and Pepr: 69 70 <!-- x-release-please-start-version --> 71 72 ```bash 73 uds deploy k3d-core-slim-dev:0.59.0 74 ``` 75 76 <!-- x-release-please-end --> 77 78 > [!IMPORTANT] 79 > The k3d-core-slim-dev bundle is intended for dev/test/demo environments and should not be used for production use. 80 81 > [!TIP] 82 > While the k3d-core-slim-dev bundle will work without internet, DNS will likely not resolve. If you are in an airgapped environment you may need to configure your /etc/hosts file such as: 83 > ``` 84 > 127.0.0.1 localhost yourAppNameHere.uds.dev sso.uds.dev keycloak.admin.uds.dev 85 > ``` 86 87 88 #### Developing UDS Core 89 90 UDS Core development leverages the `uds zarf dev deploy` command. For convenience, a UDS Task is provided to setup the environment. You'll need to have [NodeJS](https://nodejs.org/en/download/) 20 or later installed to continue. Here's an example of a flow developing the [identity-authorization layer](./packages/identity-authorization/README.md): 91 92 ```bash 93 # Create the dev environment 94 uds run dev-setup 95 96 # If developing the Pepr module: 97 npx pepr dev 98 99 # If not developing the Pepr module (can be run multiple times): 100 npx pepr deploy --yes 101 102 # Deploy the layer (can be run multiple times) 103 uds run dev-deploy --set LAYER=identity-authorization 104 ``` 105 106 #### Testing UDS Core 107 108 You can perform a complete test of UDS Core by running the following command: 109 110 ```bash 111 uds run test-uds-core 112 ``` 113 114 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: 115 116 ```bash 117 uds run test-single-layer --set LAYER=identity-authorization 118 ``` 119 120 Note you can specify the `--set FLAVOR=registry1` flag to test using Iron Bank images instead of the upstream images. 121 122 ## UDS Core Architecture Overview 123 <!-- @lulaStart 7d855a1f-5735-498a-95ad-f0d2fa572cb1 --> 124  125 <!-- @lulaEnd 7d855a1f-5735-498a-95ad-f0d2fa572cb1 --> 126 Diagrams are located in `/docs/.images`. See the [diagram README](./docs/.images/diagrams/README.md) for an explanation and help customizing.