Review enclave configuration file structure

[robszumski]

When working through the architecture and command docs in #19 it was clear to me that we need to tweak a few things in the configuration file.

1. Use the name "configuration", not "policy" since its more than just policy now
2. The image inputs and outputs are a little confusing. What if we embrace nesting to make it a bit clearer:

version: v1
name: example-enclave
image:
  from: foobar:latest
  output_tag: latest

3. We need to figure out which or all of these should be override-able with flags and what the relationship is. I would propose the order of precedence is flag > env var > config file and we log out when we see conflicts or just log out all of the detected env vars since it will be clear which flags are set. For nested items in the config file, we need a consistent scheme for "flattening" them.
4. Figure out how we want to do dashes and underscores. Flags feel better with dashes (--image-from) but env vars feel better with userscores (ENC_IMAGE_FROM). The policy file could go either way. For prior art, Kubernetes skips this issue by using camel case in its objects (outputTag)

[robszumski]

3. We need to figure out which or all of these should be override-able with flags and what the relationship is. I would propose the order of precedence is flag > env var > config file and we log out when we see conflicts or just log out all of the detected env vars since it will be clear which flags are set. For nested items in the config file, we need a consistent scheme for "flattening" them.
4. Figure out how we want to do dashes and underscores. Flags feel better with dashes (--image-from) but env vars feel better with userscores (ENC_IMAGE_FROM). The policy file could go either way. For prior art, Kubernetes skips this issue by using camel case in its objects (outputTag)

Covered these two in #19, assuming it lands and 2 above is ratified.

[robszumski]

As part of closing this issue:

• Update Create the Enclave Configuration section in app guide
• Update Create the Policy in vault guide

[russellhaering]

@robszumski is your thinking on output_tag that we would use the name (that might be the wrong word, but "foobar" in your example) for the output image, but apply whatever tag you indicate here?

Ie, in your example we would overwrite foobar:latest?

[russellhaering]

What if we did:

version: v1
name: example-enclave
images: 
  from: foobar:latest
  target: foobar-enclave:latest

Where either from or target can be just a name, or a name:tag.

In other words:

1. Explicitly separate the top-level name field (which I think we can document as basically informational metadata, which maybe gets passed through to the enclave) from anything image related.
2. Call the section "images" (plural), to clarify that it refers to two images
3. Try to make the behavior of from (could call it source) and target very similar - parallel structure and all that.

[robszumski]

@robszumski is your thinking on output_tag that we would use the name (that might be the wrong word, but "foobar" in your example) for the output image, but apply whatever tag you indicate here?
Ie, in your example we would overwrite foobar:latest?

I was thinking we would output: name + tag, eg example-enclave:latest. But I see how that is unclear :)

What if we did:

@russellhaering +1, love it

---

Do you think it is too magical to tag the target with the from tag, if you omit it on the target?

images: 
  from: foobar:hello
  target: foobar-enclave

The above outputs an image foobar-enclave:hello. I'm thinking this benefits you when you want them synced up but you're doing CI with a tag computed as part of the run, aka can't be encoded into the config file easily:

enclaver build \
  -f enclaver.yaml \
  --images-from registry.ci.example.com/foobar:18ee24150dcb1d96752a4d6dd0f20dfd8ba8c38527e40aa8509b7adecf78f9c6

That command would output foobar-enclave:18ee24150dcb1d96752a4d6dd0f20dfd8ba8c38527e40aa8509b7adecf78f9c6

---

On the naming, it would be nice to use pairs that make sense together:

• from/to
• source/target
• source/destination
• source/output