Concept machine and instance

[karajan1001]

Follow #6855 (comment)

We have machine, instance, and config, status with them, They are a bit confusing in the current unreleased documents.
So maybe it's time to fix the name and usage for each of the concepts.

Currently, machine is a template or a Metaclass object, while instance represents the actual running server, generated from one machine. So machine here is only an abstract concept, it is only a name of config and does not represent any Cloud/Server in the real world. With this machine config, we can generate an actual instance from it that is called instance. instance here actually represent a real word machine / virtual machine. It can't be configured directly. It only has status and has a similar value to the machine that generated it.

Currently, we have dvc machine list and dvc machine status these two similar commands, one is for machine to show the config from them, the other is for instance to show the running status.

name	attributes of it	show cmd
machine	config	machine list
instance	status	machine status

machine sometimes represents the concept of a config, sometimes represents a remote machine and it is also used in the first level in commands makes it more confusing.

Another question is that should the machine and instance here be a one-to-one relationship?

@dberenbaum , @jorgeorpinel , @pmrowla

[dberenbaum]

Your table looks good to me as long as we are consistent with it. It seems to parallel docker images vs containers.

Another question is that should the machine and instance here be a one-to-one relationship?

I don't think we should assume a 1-1 relationship, although for now only 1-1 is possible. Having a cluster of identical workers will definitely be needed. This could be handled either by having multiple instances or by having a single instance that defines a kubernetes cluster or something similar, but I don't see much downside in keeping open the option of having multiple instances per machine config.

[karajan1001]

How about dvc mach-inst/mach-res

[dberenbaum]

I don't have a strong preference between dvc mach inst and dvc mach-inst. Seeing them written out, my concern with both is that it's unclear what they do until you already know what they are short for.

Another option is to make machine == instance and organize like:

• dvc machine
  • spec
    • add
    • remove
    • ...
  • build
  • destroy
  • ...

(or have a separate dvc machine-spec command)

Some nice things about this layout:

• The spec commands should be less frequently used than the instance commands.
• instance is a tricky name -- does it make sense if we support k8s clusters or on-prem hpc in the future?
• spec is a commonly understood abbreviation that makes sense.

[karajan1001]

• dvc machine
  • spec
    ...

This kind of structure makes sense to me.

[jorgeorpinel]

Oops sorry for very late replies... Not sure this is still relevant but re list/status:

we could have a single command that shows both ... but IMO it makes more sense to keep them separate.
I also think that makes sense to keep list/status separated.
I agreed to keep list/status separated.

@pmrowla @daavoo @karajan1001 why do you think so though? I'd err on the side of consolidating unless there's a good reason not to. Also this idea of machines having a status is misleading as they're assumed to be always on I think. We mean whether an experiment is running on them right? That's narrow enough to include in machine list I think.

we check the remote status with dvc status --remote.

Hmmm AFAIK that shows the project status (compared to remotes), not status of remotes per se (do they even have statuses?) so it seems OK @daavoo.

[jorgeorpinel]

It would be more clear if we had separate command namespaces, like machine config list/add/remove and machine instance create/destroy. Is that too long?

Too long indeed @dberenbaum. I think a single 2nd level under dvc machine can include all the necessary commands in 3 groups: add/modify/remove for config, list show configs, their instances & status, and build/destroy to manage instances. That's all we need right? If so I sustain my previous vote.

• dvc machine
• spec
  • add
  • ...
• build
• ...

Similar to this, but the spec level is just skipped for simplicity.

I vote to add the extra level but keep the names short, like mach res/conf/spec/infra/type add and mach inst build.

I don't mind the mach name (sounds like moving very fast, could be a cool feature name) but I'd def. spell out the subcommands ("mach inst" is too cryptic).

what do you think about separating into two parts ... machine/instance ?
We could go with resource and instance to match the TPI naming

@dberenbaum @pmrowla dvc resource sounds like a more general concept. Maybe remotes are resources, etc. Unless we plan to encapsulate all resources for other features here, I'd try keep all of this under a single level-1 command for now. dvc machine or dvc instance can both work IMO (one or the other).

---

Summarizing my proposal:

dvc mach(ine) add/modify/remove - config commands (consistent with existing features)
dvc mach(ine) build/destroy - manage machines (config 1 - * instance)
dvc mach(ine) list - list configs and their instances +"status" (whether exps are running somewhere)

[jorgeorpinel]

confusing in the current unreleased documents

Meaning https://www.notion.so/iterative/215a0767aa0341d892b52767e58e2ac6 (outdated) and https://github.com/iterative/dvc/wiki/Remote-executors (incomplete) ? Or are there any more internal docs somewhere

There's also https://github.com/iterative/terraform-provider-iterative/blob/master/README.md which isn't internal and has the same issue to some extent (especially with term "machine", since "instance" has a clear meaning within that context).

[casperdcl]

CML/TPI uses:

• runner
  • cml subcommand name
  • CI provider concept (GH/GL/BB)
• executor
  • CI provider backend orchestrator (mostly just GL)
• resource
  • config entry (within main.tf files)
• instance
  • compute provider server (eg AWS EC2 t2.micro)
• machine
  • not really used afaik

[jorgeorpinel]

runner is a SCM runner

What is an SCM runner @DavidGOrtega ? Mostly curious. Thanks

[jorgeorpinel]

machine
not really used afaik

@casperdcl yeah I only see the term in the notes for instance_type: "You can also specify vendor specific machines in AWS"

[casperdcl]

hmm yes we should be more careful to avoid unneeded synonyms...

[pmrowla]

What is an SCM runner

@jorgeorpinel "runner" is what's used by github/gitlab for the machine/environment that runs a github actions/gitlab CI action (https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners)

[dberenbaum]

Here's the related references on subcommands in CLI design: https://clig.dev/#subcommands. Also, off topic, I like this diagram:

https://cloud.ibm.com/docs/containers?topic=containers-kubernetes-service-cli

@jorgeorpinel What do you think about something like that in the docs?