coco docs: clarify platforms page and agent policy - #479
Conversation
Documentation preview |
mikemckiernan
left a comment
mikemckiernan
left a comment
There was a problem hiding this comment.
A few nits, PLMK if I'm within horseshoe and hand-grenade distance.
| The Kata agent runs inside the guest virtual machine and manages the container lifecycle. | ||
| Because the Kata shim on the host is outside the TEE, the host can still issue Agent API calls | ||
| into the guest unless you restrict them. | ||
| An agent security policy is a Rego policy that the agent enforces so that only the operations |
There was a problem hiding this comment.
sugg: newly introduced or defined terms are italicized on first use--that's the "hey, this bit is important" signal.
| An agent security policy is a Rego policy that the agent enforces so that only the operations | |
| An _agent security policy_ is a Rego policy that the agent enforces so that only the operations |
| `Agent Policy generation tool <https://github.com/kata-containers/kata-containers/blob/main/src/tools/genpolicy/README.md>`_ | ||
| documentation. | ||
|
|
||
| #. Run ``genpolicy`` against the manifest you will deploy, for example: |
There was a problem hiding this comment.
nit: Use present tense whenever possible. It's usually clearest. In this case the loss of the second-person "you" is OK because the instructional text is imperative anyway.
| #. Run ``genpolicy`` against the manifest you will deploy, for example: | |
| #. Run ``genpolicy`` against the manifest to deploy: |
| The Kata Containers ``genpolicy`` tool reads your Kubernetes YAML, infers the intended Agent API | ||
| calls, encodes the policy in base64, and appends it as an annotation on the same file. | ||
|
|
||
| #. Obtain ``genpolicy`` from the latest Kata Containers release that is compatible with this |
There was a problem hiding this comment.
Maybe? Obtain feels a little wordy. Not critical.
| #. Obtain ``genpolicy`` from the latest Kata Containers release that is compatible with this | |
| #. Download ``genpolicy`` from the latest Kata Containers release that is compatible with this |
There was a problem hiding this comment.
@mikemckiernan - yes. @fidencio, to me, download seems right here as genpolicy is published as part of kata releases - do you want to get a bit more specific here?
|
|
||
| $ genpolicy -y cuda-vectoradd-kata.yaml | ||
|
|
||
| #. Review the generated policy before you apply the manifest. |
There was a problem hiding this comment.
nit: This is good instructional imperative text, but it seems (to me) to be part of the preceding step of generating the agent security policy, not a new task.
| #. Review the generated policy before you apply the manifest. | |
| Review the generated policy before you apply the manifest. |
| $ genpolicy -y cuda-vectoradd-kata.yaml | ||
|
|
||
| #. Review the generated policy before you apply the manifest. | ||
| Auto-generated policy is a starting point. |
There was a problem hiding this comment.
| Auto-generated policy is a starting point. | |
| The automatically-generated policy is a starting point. |
|
|
||
| #. Review the generated policy before you apply the manifest. | ||
| Auto-generated policy is a starting point. | ||
| It can allow operations you do not want, such as ``kubectl exec``, or omit operations your |
There was a problem hiding this comment.
nit: restating the noun is clearer than a pronoun
| It can allow operations you do not want, such as ``kubectl exec``, or omit operations your | |
| The policy can allow operations you do not want, such as ``kubectl exec``, or omit operations your |
|
|
||
| Attestation is necessary but not sufficient for a secure end-to-end deployment. | ||
| The Kata shim on the host remains untrusted and can still issue Agent API calls into the guest | ||
| unless you restrict them with a Kata agent security policy. |
There was a problem hiding this comment.
nit: pronouns are generally bad and it's better to restate the noun. Unfortunately, this is a bit of a guess:
| unless you restrict them with a Kata agent security policy. | |
| unless you restrict the Agent API calls that the host can make with a Kata agent security policy. |
There was a problem hiding this comment.
Ack - also addressing same pattern in confidential-containers/configure-workloads.rst
| * It selects a TEE-aware Kata runtime class instead of the default ``runc``-based runtime. | ||
| * It requests GPU and NVSwitch resources using the resource types advertised by the NVIDIA | ||
| Kata sandbox device plugin, which can be either default names or model-specific names. | ||
| * For NVSwitch-based HGX systems, it requests every GPU and NVSwitch on the node together so | ||
| that all devices reside inside the same Confidential Container virtual machine. | ||
| * For an attested production deployment, it includes a Kata agent security policy that limits | ||
| which Agent API calls the untrusted host can make into the guest. |
There was a problem hiding this comment.
This is a little outside the bounds of the PR, but continuing my penchant for hunting pronouns for sport, could "it" in these bullets be replaced with "the manifest"?
As a newcomer, this list is teeming with terms and I had to backtrack to remind myself what "it" was.
There was a problem hiding this comment.
agreed - I am addressing this as well for the three other bullet points listed above
4906897 to
2e9ee25
Compare
|
New revision with PR comments addressed: https://github.com/NVIDIA/cloud-native-docs/compare/490689733d40bb10003288e0e37eb888ac59668a..2e9ee2527e2445e280d6cf5a3907d90072368dc6 |
Rename the supported platforms page to include software components, and document attaching a Kata agent security policy for attested production workloads. Signed-off-by: Manuel Huber <manuelh@nvidia.com>
2e9ee25 to
34eea2d
Compare
|
@fitzthum - one more change intended to streamline agent policy + attestation in a better way: https://github.com/NVIDIA/cloud-native-docs/compare/2e9ee2527e2445e280d6cf5a3907d90072368dc6..34eea2df421ecca92ab169c4ed9e940e99429ce1 - maybe better to read the PR again instead though. |
mikemckiernan
left a comment
mikemckiernan
left a comment
There was a problem hiding this comment.
/lgtm
I opened this PR, so GH won't allow me to approve, but I'd approve. lmk if there's anything else you need from me.
| * Using sealed secrets | ||
| * Requesting secrets directly from workloads | ||
|
|
||
| A complete attestation process should also cover the Kata Agent API surface: which operations the |
There was a problem hiding this comment.
| A complete attestation process should also cover the Kata Agent API surface: which operations the | |
| A complete attestation process manages the Kata Agent API surface: which operations the |
This gist here is that "should" is the kiss of death in tech docs and is best replaced with more decisive language. Please sub in the correct verb in place of "manages", maybe "constrains" or "limits."
| Because the Kata shim on the host is outside the TEE, the host can still issue Agent API calls | ||
| into the guest unless you restrict those Agent API calls. |
There was a problem hiding this comment.
Q: does an "untrusted host" belong somewhere in here? I thought I read that before and that's what gets this human's attention. Is this correct?
| Because the Kata shim on the host is outside the TEE, the host can still issue Agent API calls | |
| into the guest unless you restrict those Agent API calls. | |
| Because the Kata shim on the host is outside the TEE, the untrusted host can still issue Agent API calls | |
| into the guest unless you restrict those Agent API calls. |
2 participants
Rename the supported platforms page to include software components, and document attaching a Kata agent security policy for attested production workloads.