From 4e46a9d2dda068eb0e00aa19772b46a5f479d26c Mon Sep 17 00:00:00 2001 From: Moritz Eckert Date: Thu, 2 May 2024 11:20:00 +0200 Subject: [PATCH 1/8] docs: add known limitations --- docs/docs/known-limitations.md | 23 +++++++++++++++++++++++ docs/sidebars.js | 5 +++++ 2 files changed, 28 insertions(+) create mode 100644 docs/docs/known-limitations.md diff --git a/docs/docs/known-limitations.md b/docs/docs/known-limitations.md new file mode 100644 index 0000000000..97afbc9ab3 --- /dev/null +++ b/docs/docs/known-limitations.md @@ -0,0 +1,23 @@ +# Known Limitations + +As Contrast is currently in an early preview stage, it's built on several projects that're also under active development. +This section outlines the most significant known limitations, providing stakeholders with clear expectations and understanding of the current state. + +## Availability + +- **Platform Support**: At present, Contrast is exclusively available on Azure AKS, supported by the [Confidential Container preview for AMD SEV-SNP](https://learn.microsoft.com/en-us/azure/confidential-computing/confidential-containers-on-aks-preview). Expansion to other cloud platforms is planned, pending the availability of necessary infrastructure enhancements. + +## Kubernetes Features + +- **Persistent Volumes**: Not currently supported within Confidential Containers. +- **Port-Forwarding**: This feature isn't yet supported by Kata Containers. +- **Resource Limits**: There is an existing bug on AKS where container memory limits are incorrectly applied. The current workaround involves using only memory requests instead of limits. + +## Runtime Policies + +- **Coverage**: While the enforcement of workload policies generally functions well, [there're scenarios not yet fully covered](https://github.com/microsoft/kata-containers/releases/tag/genpolicy-0.6.2-5). It's crucial to review deployments specifically for these edge cases. +- **Policy Evaluation**: The current policy evaluation mechanism on API requests isn't stateful, which means it cannot ensure a prescribed order of events. Consequently, there's no guaranteed enforcement that the [initializer](components/index.md#the-initializer) container runs *before* the workload container. This order is vital for ensuring that all traffic between pods is securely encapsulated within TLS connections. TODO: Consequences + +## Tooling Integration + +- **CLI Availability**: The CLI tool is currently only available for Linux. This limitation arises because certain upstream dependencies haven't yet been ported to other platforms. diff --git a/docs/sidebars.js b/docs/sidebars.js index f6e8b71ace..cc5c5bf94c 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -127,6 +127,11 @@ const sidebars = { }, ] }, + { + type: 'doc', + label: 'Known limitations', + id: 'known-limitations', + }, { type: 'category', label: 'About', From a809bc0bdec49ae907e482f7835a20182b9503d1 Mon Sep 17 00:00:00 2001 From: Moritz Eckert Date: Thu, 2 May 2024 11:28:55 +0200 Subject: [PATCH 2/8] fix vale --- docs/docs/known-limitations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/known-limitations.md b/docs/docs/known-limitations.md index 97afbc9ab3..0bf254ab0b 100644 --- a/docs/docs/known-limitations.md +++ b/docs/docs/known-limitations.md @@ -1,6 +1,6 @@ # Known Limitations -As Contrast is currently in an early preview stage, it's built on several projects that're also under active development. +As Contrast is currently in an early preview stage, it's built on several projects that are also under active development. This section outlines the most significant known limitations, providing stakeholders with clear expectations and understanding of the current state. ## Availability @@ -15,8 +15,8 @@ This section outlines the most significant known limitations, providing stakehol ## Runtime Policies -- **Coverage**: While the enforcement of workload policies generally functions well, [there're scenarios not yet fully covered](https://github.com/microsoft/kata-containers/releases/tag/genpolicy-0.6.2-5). It's crucial to review deployments specifically for these edge cases. -- **Policy Evaluation**: The current policy evaluation mechanism on API requests isn't stateful, which means it cannot ensure a prescribed order of events. Consequently, there's no guaranteed enforcement that the [initializer](components/index.md#the-initializer) container runs *before* the workload container. This order is vital for ensuring that all traffic between pods is securely encapsulated within TLS connections. TODO: Consequences +- **Coverage**: While the enforcement of workload policies generally functions well, [there are scenarios not yet fully covered](https://github.com/microsoft/kata-containers/releases/tag/genpolicy-0.6.2-5). It's crucial to review deployments specifically for these edge cases. +- **Policy Evaluation**: The current policy evaluation mechanism on API requests isn't stateful, which means it can't ensure a prescribed order of events. Consequently, there's no guaranteed enforcement that the [initializer](components/index.md#the-initializer) container runs *before* the workload container. This order is vital for ensuring that all traffic between pods is securely encapsulated within TLS connections. TODO: Consequences ## Tooling Integration From df3d04a3d7f0ead0b82923e2e8bde8222176cd3d Mon Sep 17 00:00:00 2001 From: Moritz Eckert Date: Thu, 2 May 2024 14:14:32 +0200 Subject: [PATCH 3/8] Apply suggestions from code review Co-authored-by: Paul Meyer <49727155+katexochen@users.noreply.github.com> --- docs/docs/known-limitations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/known-limitations.md b/docs/docs/known-limitations.md index 0bf254ab0b..e8c6670b31 100644 --- a/docs/docs/known-limitations.md +++ b/docs/docs/known-limitations.md @@ -1,11 +1,11 @@ # Known Limitations -As Contrast is currently in an early preview stage, it's built on several projects that are also under active development. +As Contrast is currently in an early development stage, it's built on several projects that are also under active development. This section outlines the most significant known limitations, providing stakeholders with clear expectations and understanding of the current state. ## Availability -- **Platform Support**: At present, Contrast is exclusively available on Azure AKS, supported by the [Confidential Container preview for AMD SEV-SNP](https://learn.microsoft.com/en-us/azure/confidential-computing/confidential-containers-on-aks-preview). Expansion to other cloud platforms is planned, pending the availability of necessary infrastructure enhancements. +- **Platform Support**: At present, Contrast is exclusively available on Azure AKS, supported by the [Confidential Container preview for AKS](https://learn.microsoft.com/en-us/azure/confidential-computing/confidential-containers-on-aks-preview). Expansion to other cloud platforms is planned, pending the availability of necessary infrastructure enhancements. ## Kubernetes Features From 2244fd907844cbebdee4e664f25382dbd2638472 Mon Sep 17 00:00:00 2001 From: Moritz Eckert Date: Thu, 2 May 2024 14:22:08 +0200 Subject: [PATCH 4/8] apply suggestions --- docs/docs/known-limitations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/known-limitations.md b/docs/docs/known-limitations.md index e8c6670b31..66b4c7ae65 100644 --- a/docs/docs/known-limitations.md +++ b/docs/docs/known-limitations.md @@ -10,7 +10,7 @@ This section outlines the most significant known limitations, providing stakehol ## Kubernetes Features - **Persistent Volumes**: Not currently supported within Confidential Containers. -- **Port-Forwarding**: This feature isn't yet supported by Kata Containers. +- **Port-Forwarding**: This feature [isn't yet supported by Kata Containers](https://github.com/kata-containers/kata-containers/issues/1693). You can [deploy a port-forwarder](https://docs.edgeless.systems/contrast/deployment#connect-to-the-contrast-coordinator) as a workaround. - **Resource Limits**: There is an existing bug on AKS where container memory limits are incorrectly applied. The current workaround involves using only memory requests instead of limits. ## Runtime Policies From f21ef527649cfd8d519969032da30f08685106e1 Mon Sep 17 00:00:00 2001 From: Moritz Eckert Date: Fri, 3 May 2024 08:30:11 +0200 Subject: [PATCH 5/8] apply suggestions --- docs/docs/known-limitations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/known-limitations.md b/docs/docs/known-limitations.md index 66b4c7ae65..98f7b09c97 100644 --- a/docs/docs/known-limitations.md +++ b/docs/docs/known-limitations.md @@ -15,8 +15,8 @@ This section outlines the most significant known limitations, providing stakehol ## Runtime Policies -- **Coverage**: While the enforcement of workload policies generally functions well, [there are scenarios not yet fully covered](https://github.com/microsoft/kata-containers/releases/tag/genpolicy-0.6.2-5). It's crucial to review deployments specifically for these edge cases. -- **Policy Evaluation**: The current policy evaluation mechanism on API requests isn't stateful, which means it can't ensure a prescribed order of events. Consequently, there's no guaranteed enforcement that the [initializer](components/index.md#the-initializer) container runs *before* the workload container. This order is vital for ensuring that all traffic between pods is securely encapsulated within TLS connections. TODO: Consequences +- **Coverage**: While the enforcement of workload policies generally functions well, [there are scenarios not yet fully covered](https://github.com/microsoft/kata-containers/releases/tag/3.2.0.azl0.genpolicy). It's crucial to review deployments specifically for these edge cases. +- **Policy Evaluation**: The current policy evaluation mechanism on API requests isn't stateful, which means it can't ensure a prescribed order of events. Consequently, there's no guaranteed enforcement that the [service mesh sidecar](components/service-mesh.md) container runs *before* the workload container. This order is vital for ensuring that all traffic between pods is securely encapsulated within TLS connections. TODO: Consequences ## Tooling Integration From bb20a71dd4764d5b97393c39015d9fdfbbf0df9e Mon Sep 17 00:00:00 2001 From: Moritz Eckert Date: Mon, 6 May 2024 08:19:29 +0200 Subject: [PATCH 6/8] apply suggestion --- docs/docs/deployment.md | 4 ++++ docs/docs/known-limitations.md | 8 +++++++- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/docs/deployment.md b/docs/docs/deployment.md index e0e4494532..cfb04cf406 100644 --- a/docs/docs/deployment.md +++ b/docs/docs/deployment.md @@ -78,6 +78,10 @@ deployment files. A `manifest.json` with the reference values of your deployment contrast generate resources/ ``` +:::warning +Please be aware that runtime policies currently have some blind spots. For example, they can't guarantee the starting order of containers. See the [current limitations](known-limitations.md#runtime-policies) for more details. +::: + ## Apply the resources Apply the resources to the cluster. Your workloads will block in the initialization phase until a diff --git a/docs/docs/known-limitations.md b/docs/docs/known-limitations.md index 98f7b09c97..9cbda32d92 100644 --- a/docs/docs/known-limitations.md +++ b/docs/docs/known-limitations.md @@ -16,7 +16,13 @@ This section outlines the most significant known limitations, providing stakehol ## Runtime Policies - **Coverage**: While the enforcement of workload policies generally functions well, [there are scenarios not yet fully covered](https://github.com/microsoft/kata-containers/releases/tag/3.2.0.azl0.genpolicy). It's crucial to review deployments specifically for these edge cases. -- **Policy Evaluation**: The current policy evaluation mechanism on API requests isn't stateful, which means it can't ensure a prescribed order of events. Consequently, there's no guaranteed enforcement that the [service mesh sidecar](components/service-mesh.md) container runs *before* the workload container. This order is vital for ensuring that all traffic between pods is securely encapsulated within TLS connections. TODO: Consequences +- **Order of events**: The current policy evaluation mechanism on API requests isn't stateful, so it can't ensure a prescribed order of events. Consequently, there's no guaranteed enforcement that the [service mesh sidecar](components/service-mesh.md) container runs *before* the workload container. This order ensures that all traffic between pods is securely encapsulated within TLS connections. +- **Absence of events**: Policies can't ensure certain events have happened. A container, such as the [service mesh sidecar](components/service-mesh.md), can be omitted entirely. Environment variables may be missing. +- **Volume integrity checks**: While persistent volumes are not supported yet, integrity checks do not currently cover other objects such as `ConfigMaps` and `Secrets`. + +:::warning +The policy limitations, in particular the missing guarantee that our service mesh sidecar has been started before the workload container affects the service mesh implementation of Contrast. Currently, this requires inspecting the iptable rules on startup or terminating TLS connections in the workload directly. +::: ## Tooling Integration From c721e32e88a50edb161c6fb8601f6db54ae7d1a8 Mon Sep 17 00:00:00 2001 From: Moritz Eckert Date: Mon, 6 May 2024 08:27:50 +0200 Subject: [PATCH 7/8] fix vale --- docs/docs/known-limitations.md | 2 +- tools/vale/styles/config/vocabularies/edgeless/accept.txt | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/docs/known-limitations.md b/docs/docs/known-limitations.md index 9cbda32d92..fcaa139472 100644 --- a/docs/docs/known-limitations.md +++ b/docs/docs/known-limitations.md @@ -18,7 +18,7 @@ This section outlines the most significant known limitations, providing stakehol - **Coverage**: While the enforcement of workload policies generally functions well, [there are scenarios not yet fully covered](https://github.com/microsoft/kata-containers/releases/tag/3.2.0.azl0.genpolicy). It's crucial to review deployments specifically for these edge cases. - **Order of events**: The current policy evaluation mechanism on API requests isn't stateful, so it can't ensure a prescribed order of events. Consequently, there's no guaranteed enforcement that the [service mesh sidecar](components/service-mesh.md) container runs *before* the workload container. This order ensures that all traffic between pods is securely encapsulated within TLS connections. - **Absence of events**: Policies can't ensure certain events have happened. A container, such as the [service mesh sidecar](components/service-mesh.md), can be omitted entirely. Environment variables may be missing. -- **Volume integrity checks**: While persistent volumes are not supported yet, integrity checks do not currently cover other objects such as `ConfigMaps` and `Secrets`. +- **Volume integrity checks**: While persistent volumes aren't supported yet, integrity checks don't currently cover other objects such as `ConfigMaps` and `Secrets`. :::warning The policy limitations, in particular the missing guarantee that our service mesh sidecar has been started before the workload container affects the service mesh implementation of Contrast. Currently, this requires inspecting the iptable rules on startup or terminating TLS connections in the workload directly. diff --git a/tools/vale/styles/config/vocabularies/edgeless/accept.txt b/tools/vale/styles/config/vocabularies/edgeless/accept.txt index 0cc735197a..9d0b883982 100644 --- a/tools/vale/styles/config/vocabularies/edgeless/accept.txt +++ b/tools/vale/styles/config/vocabularies/edgeless/accept.txt @@ -53,6 +53,7 @@ initramfs Inkscape iodepth IPSec +iptable Istio journald Kata From e61f2a6c1c3144b44d355ba5abb7f2beaf1613b5 Mon Sep 17 00:00:00 2001 From: Moritz Eckert Date: Mon, 6 May 2024 08:47:59 +0200 Subject: [PATCH 8/8] Update docs/docs/known-limitations.md Co-authored-by: Markus Rudy --- docs/docs/known-limitations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/known-limitations.md b/docs/docs/known-limitations.md index fcaa139472..27cf2a1664 100644 --- a/docs/docs/known-limitations.md +++ b/docs/docs/known-limitations.md @@ -21,7 +21,7 @@ This section outlines the most significant known limitations, providing stakehol - **Volume integrity checks**: While persistent volumes aren't supported yet, integrity checks don't currently cover other objects such as `ConfigMaps` and `Secrets`. :::warning -The policy limitations, in particular the missing guarantee that our service mesh sidecar has been started before the workload container affects the service mesh implementation of Contrast. Currently, this requires inspecting the iptable rules on startup or terminating TLS connections in the workload directly. +The policy limitations, in particular the missing guarantee that our service mesh sidecar has been started before the workload container affects the service mesh implementation of Contrast. Currently, this requires inspecting the iptables rules on startup or terminating TLS connections in the workload directly. ::: ## Tooling Integration