[doc] commission does not fail NEW nodes

[khb]

MAAS 2.5 documentation says: "A machine in the 'ready', 'declared' or 'failed test' state may initiate a commissioning cycle where it is checked out and tested in preparation for transitioning to the 'ready' state. If it is already in the 'ready' state this is considered a re-commissioning process which is useful if commissioning tests were changed after it previously commissioned."
======================
But both the CLI and the restful API are allowing "NEW" as well, in both MAAS 2.4 and 2.5

Unclear if this is "just" a documentation issue, or if there is a failure to enforce a constraint. Personally, I don't see why NEW isn't listed as a valid state for this API.

steps:

1) locate a node in the NEW state (say s3aq7d)
2) Use API to commission

POST /MAAS/api/2.0/machines/s3aq7d/?format=json& op=commission HTTP/1.1
Host: 100.80.70.8:5240
Accept: application/json
cache-control: no-cache
Postman-Token: 19c486d8-cd2f-4503-b7b9-e60b0f09d364

3) Observe success

[khb (khbkhb)]

and MAAS 2.3
MAAS version: 2.3.5 (6511-gf466fdb-0ubuntu1)

[Lee Trager (ltrager)]

This is a documentation issue. A machine must be commissioned before it can be used. A NEW machine means commissioning hasn't been run or in 2.5+ it has been run but hasn't been accepted by an administrator.

[Bill Wear (billwear)]

This whole confusion of how MAAS actually processes nodes in various states versus the policy that the documentation lays out is annoying me as an "unclear thing." When 2.9 pops out, I'm going to test it, figure out what MAAS actually does, and document that, possibly with guidance on what's recommended, but with accuracy about what will work.

[Bill Wear (billwear)]

After looking through the 2.5 documentation, I cannot find a passage which matches what's been quoted above. Please provide a URL to the page where this error occurs. The remainder of the MAAS documentation (2.6++) seems to be relatively okay on this point. Marking incomplete.

[khb (khbkhb)]

Don't have the time or patience to track down 2.5. The documentation in this area continues to evolve, so. https://maas.io/docs/concepts-and-terms#heading--controllers "Commission
This action commissions a node, changing a node’s status from ‘New’ to ‘Commissioning’ to ‘Ready’."

Of course, taken by itself this could be read as the older documentation that New->Commission->Ready means has to start with New. But later it speaks of the need to recommission if/when networking or storage changes are made. In fact, what I believe is intended, is that Commission is allowed from (New|Ready|Failed ....). Would it kill us to simply have a formal state diagram somewhere?

[Bill Wear (billwear)]

No, a formal state diagram is a good idea, and it's on the list. It's just
a long list.

On Thu, Dec 10, 2020 at 12:40 PM khb <email address hidden> wrote:

> Don't have the time or patience to track down 2.5. The documentation in
> this area continues to evolve, so.
> https://maas.io/docs/concepts-and-terms#heading--controllers "Commission
> This action commissions a node, changing a node’s status from ‘New’ to
> ‘Commissioning’ to ‘Ready’."
>
> Of course, taken by itself this could be read as the older documentation
> that New->Commission->Ready means has to start with New. But later it
> speaks of the need to recommission if/when networking or storage changes
> are made. In fact, what I believe is intended, is that Commission is
> allowed from (New|Ready|Failed ....). Would it kill us to simply have a
> formal state diagram somewhere?
>
> --
> You received this bug notification because you are a bug assignee.
> https://bugs.launchpad.net/bugs/1812896
>
> Title:
> [doc] commission does not fail NEW nodes
>
> Status in MAAS:
> Incomplete
>
> Bug description:
> MAAS 2.5 documentation says: "A machine in the 'ready', 'declared' or
> 'failed test' state may initiate a commissioning cycle where it is checked
> out and tested in preparation for transitioning to the 'ready' state. If it
> is already in the 'ready' state this is considered a re-commissioning
> process which is useful if commissioning tests were changed after it
> previously commissioned."
> ======================
> But both the CLI and the restful API are allowing "NEW" as well, in both
> MAAS 2.4 and 2.5
>
> Unclear if this is "just" a documentation issue, or if there is a
> failure to enforce a constraint. Personally, I don't see why NEW isn't
> listed as a valid state for this API.
>
> steps:
>
> 1) locate a node in the NEW state (say s3aq7d)
> 2) Use API to commission
>
> POST /MAAS/api/2.0/machines/s3aq7d/?format=json&amp; op=commission
> HTTP/1.1
> Host: 100.80.70.8:5240
> Accept: application/json
> cache-control: no-cache
> Postman-Token: 19c486d8-cd2f-4503-b7b9-e60b0f09d364
>
> 3) Observe success
>
> To manage notifications about this bug go to:
> https://bugs.launchpad.net/maas/+bug/1812896/+subscriptions
>

--
Bill Wear, MAAS Developer Advocate

[Bill Wear (billwear)]

State diagram completed and added to documentation. This is fixed.