Skip to content

Commit ae6bfa7

Browse files
gambol99gambol99
committed
docs: updating the structure and some of the docs
1 parent 36215c9 commit ae6bfa7

File tree

8 files changed

+268
-4
lines changed

8 files changed

+268
-4
lines changed

‎docs/docs/catalog/features.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Product Features
2+
3+
## Features
4+
5+
The following provides a collection of addons, description and the feature flag (i.e. a label within the cluster definition) to enable it.
6+
7+
| Chart | Namespace | Description | Feature Flag |
8+
|-------|-----------|-------------|-------------|
9+
| metrics-server | kube-system | Collects resource metrics from Kubelets for pod autoscaling and kubectl top | enable_metrics_server |
10+
| volcano | volcano-system | Batch system and job scheduler for high-performance workloads | enable_volcano |
11+
| cert-manager | cert-manager | Automatic certificate management for Kubernetes | enable_cert_manager |
12+
| cluster-autoscaler | kube-system | Automatically adjusts the size of Kubernetes clusters | enable_cluster_autoscaler |
13+
| external-dns | kube-system | Synchronizes exposed Services and Ingresses with DNS providers | enable_external_dns |
14+
| external-secrets | external-secrets | Integrates external secret management systems with Kubernetes | enable_external_secrets |
15+
| argo-cd | argocd | Declarative GitOps continuous delivery tool | enable_argocd |
16+
| argo-events | argocd | Event-driven workflow automation framework | enable_argo_events |
17+
| argo-rollouts | argocd-rollouts | Progressive delivery controller for Kubernetes | enable_argo_rollouts |
18+
| argo-workflows | argo-workflows | Workflow engine for Kubernetes | enable_argo_workflows |
19+
| ingress-nginx | ingress-nginx | Ingress controller for Kubernetes using NGINX | enable_ingress_nginx |
20+
| keda | keda-system | Kubernetes-based Event Driven Autoscaling | enable_keda |
21+
| kro | kro-system | Kubernetes Resource Operator for custom resources | enable_kro |
22+
| kube-prometheus-stack | prometheus | Monitoring and alerting stack including Prometheus, Grafana, and Alertmanager | enable_kube_prometheus_stack |
23+
| kyverno | kyverno-system | Kubernetes native policy management | enable_kyverno |
24+
| prometheus-adapter | prometheus | Adapter to use Prometheus metrics with Kubernetes HPA | enable_prometheus_adapter |
25+
| secrets-store-csi-driver | kube-system | Interface between Kubernetes and external secret stores | enable_secrets_store_csi_driver |
26+
| vpa | kube-system | Vertical Pod Autoscaler for automatic CPU and memory requests | enable_vpa |

‎docs/docs/catalog/overview.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Catalog Overview

‎docs/docs/getting-started/standalone-aws.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Building Standalone Cluster in AWS
2+
3+
!!! note "Note"
4+
5+
This documentation is a work in progress and is subject to change. Please check back regularly for updates.
6+
7+
This repository includes a terraform pipeline / codebase to validate locally a standalone build within AWS infrastructure. Enabling the platform team to validate any changes, add-ons, configurations and so forth before taking it to a revision.
8+
9+
## Prerequisites
10+
11+
- AWS CLI (<https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html>)
12+
- Kubectl (<https://kubernetes.io/docs/tasks/tools/#kubectl>)
13+
- Terraform (<https://developer.hashicorp.com/terraform/downloads>)
14+
15+
## Terraform
16+
17+
The terraform codebase can be found in the `terraform` directory. This currently uses two modules to handle the provisioning.
18+
19+
- [terraform-aws-eks](https://github.com/gambol99/terraform-aws-eks) - This module provisions the EKS cluster, networking, iam roles and so on.
20+
- [terraform-kube-platform](https://github.com/gambol99/terraform-kube-platform) - This module provisions the platform components, such as ArgoCD and bootstraps the cluster with the platform.

‎docs/docs/platform/overview.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Platform Overview
2+
3+
!!! note "Note"
4+
5+
This documentation is a work in progress and is subject to change. Please check back regularly for updates.
6+
7+
---
8+
9+
This section provides an overview of the core features and capabilities of the Kubernetes platform. The platform includes:
10+
11+
- **Security Controls**: Built-in security policies and controls via Kyverno to enforce best practices
12+
- **Multi-Tenancy**: Namespace isolation and resource management for multiple teams/workloads
13+
- **GitOps Workflows**: Declarative application delivery and configuration management
14+
- **Observability**: Integrated monitoring, logging and tracing capabilities
15+
- **Developer Experience**: Streamlined workflows and tools for application teams
16+
17+
The following sections detail the specific components and features available in the platform.

‎docs/docs/platform/security/kyverno.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Kyverno Policies
2+
3+
## Overview
4+
5+
Kyverno is a policy engine designed for Kubernetes that validates, mutates, and generates configurations using policies as Kubernetes resources. It provides key features like:
6+
7+
- Policy validation and enforcement
8+
- Resource mutation and generation
9+
- Image verification and security controls
10+
- Audit logging and reporting
11+
- Admission control webhooks
12+
13+
The following policies are shipped by default in this platform to enforce security best practices, resource management, and operational standards.
14+
15+
For detailed information about Kyverno's capabilities, refer to the [official documentation](https://kyverno.io/docs/) or [policy library](https://kyverno.io/policies/).
16+
17+
---
18+
## :material-shield-lock: Rule: deny-empty-ingress-host
19+
20+
**Category:** Best Practices | **Severity:** medium | **Scope:** Cluster-wide
21+
22+
An ingress resource needs to define an actual host name in order to be valid. This policy ensures that there is a hostname for each rule defined.
23+
24+
**Rules**
25+
26+
- **disallow-empty-ingress-host** (Validation)
27+
28+
---
29+
30+
## :material-shield-lock: Rule: require-labels
31+
32+
**Category:** Best Practices | **Severity:** medium | **Scope:** Cluster-wide
33+
34+
Define and use labels that identify semantic attributes of your application or Deployment. A common set of labels allows tools to work collaboratively, describing objects in a common manner that all tools can understand. The recommended labels describe applications in a way that can be queried. This policy validates that the labels `app.kubernetes.io/name`, `app.kubernetes.io/version`, and `app.kubernetes.io/part-of` are specified with some value.
35+
36+
**Rules**
37+
38+
- **check-for-labels** (Validation)
39+
40+
- **check-deployment-template-labels** (Validation)
41+
42+
---
43+
44+
## :material-shield-lock: Rule: deny-no-limits
45+
46+
**Category:** Best Practices, EKS Best Practices | **Severity:** medium | **Scope:** Cluster-wide
47+
48+
As application workloads share cluster resources, it is important to limit resources requested and consumed by each Pod. It is recommended to require resource requests and limits per Pod, especially for memory and CPU. If a Namespace level request or limit is specified, defaults will automatically be applied to each Pod based on the LimitRange configuration. This policy validates that all containers have something specified for memory and CPU requests and memory limits.
49+
50+
**Rules**
51+
52+
- **validate-resources** (Validation)
53+
54+
---
55+
56+
## :material-shield-lock: Rule: deny-external-secrets
57+
58+
**Category:** Security | **Severity:** medium | **Scope:** Cluster-wide
59+
60+
When provisioning ExternalSecrete, the key must be prefixed with the namespace name to ensure proper isolation and prevent unauthorized access.
61+
62+
**Rules**
63+
64+
- **namespace-prefix** (Validation)
65+
- Applies to: ExternalSecret
66+
67+
---
68+
69+
## :material-shield-lock: Rule: deny-nodeport-service
70+
71+
**Category:** Best Practices | **Severity:** medium | **Scope:** Cluster-wide
72+
73+
A Kubernetes Service of type NodePort uses a host port to receive traffic from any source. A NetworkPolicy cannot be used to control traffic to host ports. Although NodePort Services can be useful, their use must be limited to Services with additional upstream security checks. This policy validates that any new Services do not use the `NodePort` type.
74+
75+
**Rules**
76+
77+
- **validate-nodeport** (Validation)
78+
79+
---
80+
81+
## :material-shield-lock: Rule: deny-default-namespace
82+
83+
**Category:** Multi-Tenancy | **Severity:** medium | **Scope:** Cluster-wide
84+
85+
Kubernetes Namespaces are an optional feature that provide a way to segment and isolate cluster resources across multiple applications and users. As a best practice, workloads should be isolated with Namespaces. Namespaces should be required and the default (empty) Namespace should not be used. This policy validates that Pods specify a Namespace name other than `default`. Rule auto-generation is disabled here due to Pod controllers need to specify the `namespace` field under the top-level `metadata` object and not at the Pod template level.
86+
87+
**Rules**
88+
89+
- **validate-namespace** (Validation)
90+
91+
- **validate-podcontroller-namespace** (Validation)
92+
93+
---
94+
95+
## :material-shield-lock: Rule: deny-latest-image
96+
97+
**Category:** Best Practices | **Severity:** medium | **Scope:** Cluster-wide
98+
99+
The ':latest' tag is mutable and can lead to unexpected errors if the image changes. A best practice is to use an immutable tag that maps to a specific version of an application Pod. This policy validates that the image specifies a tag and that it is not called `latest`.
100+
101+
**Rules**
102+
103+
- **require-image-tag** (Validation)
104+
105+
- **validate-image-tag** (Validation)
106+
107+
---
108+
109+
## :material-shield-lock: Rule: deny-no-pod-probes
110+
111+
**Category:** Best Practices, EKS Best Practices | **Severity:** medium | **Scope:** Cluster-wide
112+
113+
Liveness and readiness probes need to be configured to correctly manage a Pod's lifecycle during deployments, restarts, and upgrades. For each Pod, a periodic `livenessProbe` is performed by the kubelet to determine if the Pod's containers are running or need to be restarted. A `readinessProbe` is used by Services and Deployments to determine if the Pod is ready to receive network traffic. This policy validates that all containers have one of livenessProbe, readinessProbe, or startupProbe defined.
114+
115+
**Rules**
116+
117+
- **deny-no-pod-probes** (Validation)
118+
119+
---
120+
121+
## :material-shield-lock: Rule: deny-cap-net-raw
122+
123+
**Category:** Best Practices | **Severity:** medium | **Scope:** Cluster-wide
124+
125+
Capabilities permit privileged actions without giving full root access. The CAP_NET_RAW capability, enabled by default, allows processes in a container to forge packets and bind to any interface potentially leading to MitM attacks. This policy ensures that all containers explicitly drop the CAP_NET_RAW ability. Note that this policy also illustrates how to cover drop entries in any case although this may not strictly conform to the Pod Security Standards.
126+
127+
**Rules**
128+
129+
- **require-drop-cap-net-raw** (Validation)
130+
131+
---
132+
133+
**Total Policies: 9**

docs/docs/tenant/applications.md renamed to docs/docs/platform/tenant/applications.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,9 @@ kustomize:
7070
path: kustomize
7171
# (Optional) Override the namespace to use for the deployment.
7272
namespace: override-namespace
73+
# (Required) Details the revision to point; this is a revision within those repository and
74+
# is used to control a point in time of the manifests.
75+
revision: <GIT+SHA>
7376
# (Optional) Patches to apply to the deployment.
7477
patches:
7578
- target:
@@ -89,3 +92,63 @@ kustomize:
8992
## This is the default value to use if the value is not found.
9093
default: "1.21.3"
9194
```
95+
96+
Unlike Helm where versions are managed externally through chart repositories, Kustomize manifests are typically stored directly in your repository. While Kustomize overlays provide environment-specific customization, changes to shared base configurations could potentially affect all environments simultaneously.
97+
98+
To provide better control and safety, the `revision` field is used to pin Kustomize deployments to a specific Git commit or branch in the tenant repository. This allows you to:
99+
100+
- Make changes to manifests in the main branch without affecting production
101+
- Control the rollout of changes across environments by updating revisions
102+
- Roll back to previous versions by reverting to earlier commits
103+
- Test changes in lower environments before promoting to production
104+
105+
**Example workflow:**
106+
107+
1. Develop and commit Kustomize changes to main branch
108+
2. Test in dev environment by updating dev cluster's revision
109+
3. Promote to staging/prod by updating their revisions after validation
110+
4. Roll back if needed by reverting to previous commit SHA
111+
112+
## :material-application-array-outline: Kustomize with External Source
113+
114+
For teams that prefer to maintain their Kustomize manifests in a separate repository, you can reference external sources directly. This provides flexibility in managing deployment configurations and allows for independent versioning strategies. A typical example would be to use floating tags to represent the environments.
115+
116+
1. Create a folder for your application (this becomes the namespace by default)
117+
2. Add the `CLUSTER_NAME.yaml` file with external repository configuration:
118+
119+
```yaml
120+
kustomize:
121+
# (Required) The URL to the kustomize repository
122+
repository: GIT_URL
123+
# (Required) The path inside the repository
124+
path: overlays/dev
125+
# (Required) Use a floating tag 'dev' for the development cluster and similar for the prod
126+
revision: dev
127+
```
128+
129+
## :material-application-array-outline: Combinational Deployment
130+
131+
You can combine both helm and kustomize deployments in a single file. This allows you to deploy applications that require both deployment methods.
132+
133+
1. Create a folder for your application, e.g. `myapp`
134+
2. Add a `CLUSTER_NAME.yaml` file that contains both helm and kustomize configurations
135+
136+
```yaml
137+
helm:
138+
## (Optional) The chart to use for the deployment.
139+
chart: ./charts/platform
140+
## (Optional) The path inside a repository to the chart to use for the deployment.
141+
path: ./charts/platform
142+
## (Required) The release name to use for the deployment.
143+
release_name: platform
144+
## (Required) The version of the chart to use for the deployment.
145+
version: 0.1.0
146+
147+
kustomize:
148+
# (Required) The path to the kustomize base.
149+
path: kustomize
150+
# (Optional) Override the namespace to use for the deployment.
151+
namespace: override-namespace
152+
# (Required) Git revision
153+
revision: git+sha
154+
```

docs/docs/tenant/system.md renamed to docs/docs/platform/tenant/system.md

File renamed without changes.

‎docs/mkdocs.yml‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ site_name: Kubernetes Platform
22
repo_url: https://github.com/gambol99/kubernetes-platform
33

44
nav:
5-
- Platform: index.md
5+
- Overview: index.md
66
- Architecture:
77
- Overview: architecture/overview.md
88
- Platform Setup: architecture/setup.md
@@ -13,9 +13,13 @@ nav:
1313
- Local Development: getting-started/local-development.md
1414
- Standalone: getting-started/standalone.md
1515
- Hub & Spoke: getting-started/central.md
16-
- Tenant Services:
17-
- Tenant Applications: tenant/applications.md
18-
- Tenant System: tenant/system.md
16+
- Platform:
17+
- Overview: platform/overview.md
18+
- Workloads:
19+
- Applications: platform/tenant/applications.md
20+
- System: platform/tenant/system.md
21+
- Security:
22+
- Kyverno Policies: platform/security/kyverno.md
1923

2024
theme:
2125
name: material

0 commit comments

Comments
 (0)