docs: Add a "Creating derived configs" section

[cgwalters]

xref openshift/machine-config-operator#1720

This also came up in e.g.
https://github.com/coreos/fedora-coreos-docs/pull/264/files#diff-089ac9657fd668d3f0f2d3dcb663fe1c75e72aaefac2ff1d78ae70c9cf96e46eR185

[cgwalters]

Oh well that's just super cool how the docs are CI tested rustdoc style. Nice work! (edit: I mean, nice work whoever wrote the testing code)

[bgilbert]

I think we should either move this to OCP docs, or substantially cut down the explanation. Outside of OCP this isn't an operation users should generally need to perform, because it assumes that (1) users are injecting machine-specific configuration fragments (which we should strongly discourage in favor of DHCP and DNS) and (2) the original worker.ign isn't under their control (which is only true if it's generated by an outside tool like openshift-install).

If we want to keep this here, we could drop most of the explanatory text and just give a couple examples:

1. merging an external config over HTTP (preferred), and
2. merging it from a local directory (if necessary).

[cgwalters]

Outside of OCP this isn't an operation users should generally need to perform, because it assumes that (1) users are injecting machine-specific configuration fragments (which we should strongly discourage in favor of DHCP and DNS)

Sure, but we clearly need to support static IP addressing etc. too right? And if we support it it should be documented.

and (2) the original worker.ign isn't under their control (which is only true if it's generated by an outside tool like openshift-install).

It's an interesting topic. I could imagine this happening outside of OpenShift 4 too. Like a "base operating system" group maintaining their tweaked base config, and then for some special machines they derive from that config in a similar way.

Dunno. If you feel strongly I can move this just to the OCP docs for now.

[cgwalters]

Comments addressed!

[cgwalters]

Any further thoughts on this?

[bgilbert]

and (2) the original worker.ign isn't under their control (which is only true if it's generated by an outside tool like openshift-install).

It's an interesting topic. I could imagine this happening outside of OpenShift 4 too. Like a "base operating system" group maintaining their tweaked base config, and then for some special machines they derive from that config in a similar way.

Thinking about it some more, I think the doc as written (with ignition.config.merge.local) should go in OCP docs.

In general, we should encourage users to maintain a library of configs that can be merged by the root config, with any machine-specific configuration (e.g. static IP) placed directly in the root config. So the root might look like:

variant: fcos
version: 1.1.0
ignition:
  config:
    merge:
      - source: https://example.com/IT-department-baseline.ign
      - source: https://example.com/standard-compute-node.ign
      - source: https://example.com/node-with-two-hard-drives.ign
      - source: https://example.com/development-cluster-node.ign
storage:
  files:
    - path: /etc/hostname
      contents:
        inline: foo.example.com

The OCP case is a bit weird because openshift-install thinks it's generating the root config, but that belief turns out to be wrong. We don't want to disrupt the "just feed the root config to the machine" workflow and we don't want to tell the user to host the worker.ign on a web server, as they normally should with a library config. Thus we end up with a workflow where users generate a "super-root" config embedding the original "root". It makes sense within OCP constraints, but it's an awkward workflow outside of that context. For one thing, the resulting Ignition config obscures part of its contents inside a gzip+base64 blob.