docs: mention the need to override the coordinator policy hash

docs/docs/components/policies.md

@@ -74,3 +74,15 @@ Contrast verifies its confidential containers following these steps:
 9. The Contrast Coordinator verifies that the started pod has a permitted policy hash in its `HOSTDATA` field.
 
 After the last step, we know that the policy hasn't been tampered with and, thus, that the workload matches expectations and may receive mesh certificates.
+
+## Platform Differences
+
+Contrast uses different rules and data sections for different platforms.
+This results in different policy hashes for different platforms.
+
+The `generate` command automatically derives the correct set of rules and data sections from the `reference-values` flag.
+
+The `verify`, `set`, and `recover` commands need to know the coordinator's expected policy hash to verify its identity.
+By default these commands assume that the coordinator is using the policy for the `AKS-CLH-SNP` platform.
+If the coordinator is running on a different platform, the correct policy hash can be looked up in the `coordinator-policy.hash` file bundled with the [Contrast release](https://github.com/edgelesssys/contrast/releases).
+The coordinator policy hash can be overwritten using the `--coordinator-policy-hash` flag.

docs/docs/deployment.md

@@ -112,10 +112,10 @@ This is useful for workloads that are hard to configure with custom certificates
 Configuration of the sidecar depends heavily on the application.
 The following example is for an application with these properties:
 
-* The container has a main application at TCP port 8001, which should be TLS-wrapped and doesn't require client authentication.
-* The container has a metrics endpoint at TCP port 8080, which should be accessible in plain text.
-* All other endpoints require client authentication.
-* The app connects to a Kubernetes service `backend.default:4001`, which requires client authentication.
+- The container has a main application at TCP port 8001, which should be TLS-wrapped and doesn't require client authentication.
+- The container has a metrics endpoint at TCP port 8080, which should be accessible in plain text.
+- All other endpoints require client authentication.
+- The app connects to a Kubernetes service `backend.default:4001`, which requires client authentication.
 
 Add the following annotations to your workload:
 
@@ -303,6 +303,10 @@ This will use the reference values from the manifest file to attest the Coordina
 After this step, the Coordinator will start issuing TLS certificates to the workloads. The init container
 will fetch a certificate for the workload and the workload is started.
 
+:::warning
+On bare metal, the [coordinator policy hash](components/policies.md#platform-differences) must be overwritten using `--coordinator-policy-hash`.
+:::
+
 ## Verify the Coordinator
 
 An end user (data owner) can verify the Contrast deployment using the `verify` command.
@@ -316,6 +320,10 @@ service mesh root certificate and the history of manifests into the `verify/` di
 referenced in the active manifest are also written to the directory. The verification will fail if the active
 manifest at the Coordinator doesn't match the manifest passed to the CLI.
 
+:::warning
+On bare metal, the [coordinator policy hash](components/policies.md#platform-differences) must be overwritten using `--coordinator-policy-hash`.
+:::
+
 ## Communicate with workloads
 
 You can securely connect to the workloads using the Coordinator's `mesh-ca.pem` as a trusted CA certificate.
@@ -375,3 +383,7 @@ existing workloads won't be able to communicate with workloads newly spawned.
 All workloads should be restarted after the recovery succeeded.
 
 :::
+
+:::warning
+On bare metal, the [coordinator policy hash](components/policies.md#platform-differences) must be overwritten using `--coordinator-policy-hash`.
+:::

docs/docs/examples/emojivoto.md

@@ -1,6 +1,7 @@
 # Confidential emoji voting
 
 <!-- TODO(katexochen): create a screenshot with fixed format -->
+
 ![screenshot of the emojivoto UI](../_media/emoijvoto.png)
 
 **This tutorial guides you through deploying [emojivoto](https://github.com/BuoyantIO/emojivoto) as a
@@ -13,6 +14,7 @@ the voting and leader board logic (`voting`). The `vote-bot` simulates user traf
 votes to the frontend.
 
 <!-- TODO(katexochen): recreate in our design -->
+
 ![emojivoto components topology](https://raw.githubusercontent.com/BuoyantIO/emojivoto/e490d5789086e75933a474b22f9723fbfa0b29ba/assets/emojivoto-topology.png)
 
 ### Motivation
@@ -128,6 +130,10 @@ The CLI will use the reference values from the manifest to attest the Coordinato
 during the TLS handshake. If the connection succeeds, it's ensured that the Coordinator
 deployment hasn't been tampered with.
 
+:::warning
+On bare metal, the [coordinator policy hash](components/policies.md#platform-differences) must be overwritten using `--coordinator-policy-hash`.
+:::
+
 ### Deploy emojivoto
 
 Now that the coordinator has a manifest set, which defines the emojivoto deployment as an allowed workload,
@@ -175,6 +181,10 @@ configuration over the established TLS channel. The CLI will store this informat
 certificate of the mesh (`mesh-ca.pem`) and the history of manifests, into the `verify/` directory.
 In addition, the policies referenced in the manifest history are also written into the same directory.
 
+:::warning
+On bare metal, the [coordinator policy hash](components/policies.md#platform-differences) must be overwritten using `--coordinator-policy-hash`.
+:::
+
 ### Manifest history and artifact audit
 
 In the next step, the Coordinator configuration that was written by the `verify` command needs to be audited.
@@ -245,6 +255,10 @@ won't trust parts of the deployment that got their certificate issued before the
 that parts of the deployment that received a security update won't be infected by parts of the deployment at an older
 patch level that may have been compromised. The `mesh-ca.pem` is updated with the new CA certificate chain.
 
+:::warning
+On bare metal, the [coordinator policy hash](components/policies.md#platform-differences) must be overwritten using `--coordinator-policy-hash`.
+:::
+
 ### Rolling out the update
 
 The Coordinator has the new manifest set, but the different containers of the app are still