Project

General

Profile

Documentation #46133

encourage users to apply YAML specs instead of using the CLI

Added by Sebastian Wagner about 2 months ago. Updated 6 days ago.

Status:
Resolved
Priority:
Normal
Assignee:
-
Category:
-
Target version:
-
% Done:

0%

Tags:
Backport:
Reviewed:
Affected Versions:
Pull request ID:

Description

Ceph orchestrator has two main ways to interact on the command line: The CLI and YAML specs.

Turnd out, the CLI is prone to some user errors that I frequently see.

  • The apply command seems to be a source of lots of confusion: When executing something like this:
ceph orch apply mon host1
ceph orch apply mon host2
ceph orch apply mon host3

which leads to only a single MON at host3.

but actually they want to run this command instead:

ceph orch apply mon "host1,host2,host3" 

Looks like the semantics of apply are not obvious.

  • The orch CLI is fairly complex with many parameters and many options. When taking into account that we don't own the ceph binary, but have to share it with the rest of Ceph, we can't control the CLI to a point where using the CLI don't generate user errors. For example, I'm seeing users where the parameters are "shifted" leading to wrong service specifications.

Consider:

ceph orch apply RGW myrealm myzone "host1,host2,host3" 

This will generate a service like this:

service_type: rgw
placement: null
spec:
  realm: myrealm
  zone: myzone
  subcluster: host1,host2,host3

Which is just wrong.

Instead.

I'd propose to encourage users to use the YAML specifications and only use

ceph orch apply -i file.yaml

And let users define YAML specifications:

service_type: mon
placement:
  hosts:
  - host1
  - host2
  - host3

Benefits are:

  • The semantics of the placement argument is clear.
  • As we're using named arguments in YAML, we'll see fewer users calling the CLI wrongly.

History

#1 Updated by Zac Dover about 2 months ago

affected files:

cephadm/adopt.rst
cephadm/install.rst
mgr/orchestrator.rst

#2 Updated by Zac Dover about 2 months ago

We need more examples of YAML files that users can cut and paste or at least cut, alter, and paste.

#3 Updated by Zac Dover about 2 months ago

This is similar to the way that Kubernetes does things.
--Sebastian Wagner, Ceph Orchestrators Meeting 22 Jun 2020

#5 Updated by Zac Dover about 1 month ago

  • Pull request ID set to 35709

#6 Updated by Sebastian Wagner 15 days ago

  • Status changed from New to Pending Backport

#7 Updated by Sebastian Wagner 6 days ago

  • Status changed from Pending Backport to Resolved

Also available in: Atom PDF