-
Notifications
You must be signed in to change notification settings - Fork 18
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
## 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 <rjferguson21@gmail.com>
- Loading branch information
1 parent
05fd407
commit a35ca7b
Showing
13 changed files
with
446 additions
and
8 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
--- | ||
title: Configure UDS Core | ||
type: docs | ||
weight: 3 | ||
--- |
9 changes: 6 additions & 3 deletions
9
docs/CONFIGURE_POLICY_EXEMPTIONS.md → ...ration/uds-configure-policy-exemptions.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
6 changes: 5 additions & 1 deletion
6
docs/MONITOR.md → docs/configuration/uds-monitoring-metrics.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
--- | ||
title: Deploying UDS Core | ||
type: docs | ||
weight: 2 | ||
--- |
Oops, something went wrong.