doc: create migration guide for enforced agent id format #3527

[SilvaMatteus]

Pull Request check list

• [X ] Commit conforms to CONTRIBUTING.md?
• [- ] Proper tests/regressions included?
• [X ] Documentation updated?

Affected functionality

Description of change

Which issue this PR fixes

https://github.com/spiffe/spire/issues/3527

[evan2645]

Thanks for the contribution @SilvaMatteus! Is it ready for review?

[SilvaMatteus]

Hi @evan2645 ,

I would like to discuss with someone the comments I left in the Markdown file before we say it is ready to review.

Like the following:

<!-- todo(matteus): mention first version which enforced the shape -->
 <!-- todo(matteus): is the following plan still valid?
 From Andrew:
 -------------------
 Warn on the undesired ID usage (this is already merged and will ship in 1.2.1. Since this was not in place for 1.2.0, we cannot change it through 1.3.x)
 -> Beginning with 1.4.0 (THIS HAS CHANGED, RIGHT?), disallow newly attested nodes which do not conform to the expected ID shape. Existing agents will still continue to operate successfully. As part of this change, we will also introduce a warning for existing IDs that are non-conformant.
 -> In 1.5.0 (or a later minor version), we will start denying agent authorization for agents with non-conformant IDs.
 -------------------
 -->

and

### Identify Non-Conforming Agent IDs:

 Use one or combine the following options to identify agent IDs that don't follow the recommended format:

 - SPIRE CLI ([spire-server entry update](https://github.com/spiffe/spire/blob/main/doc/spire_server.md#spire-server-entry-update))
 - SPIRE server logs
 - [Agent configuration](https://github.com/spiffe/spire/tree/main/doc)

 <!-- todo(matteus): which are other methods that may be available? -->

(just noticed the SPIRE CLI command would be actually spire-server entry show)

I contacted @azdagron via Slack, but he did not have time yet to answer that. If you do have time before Andrew does, @evan2645 , here are some points I would like to discuss:

- The versions we are going to put in the migration guide
- The level of details and format of the document (I am preparing a first version of the doc right now)
- Where to put the final document

When we have this PR ready, I would also start the implementation side.

Thanks!

[SilvaMatteus]

Sorry for the long latency getting back to you @SilvaMatteus 😮‍💨 If you are still interested in continuing this work, I've left a few comments. Also, @zmt has been through this scenario and has volunteered to help guide you as you author this document (thanks @zmt!).

Hi!

All good, I also took a long time to come up with the first draft. Thanks for the comments. I will reach @zmt out in Slack.

Thanks folks.

[azdagron]

This PR has been open a while without activity. I'll go ahead and close this for now. If/when progress is made, please feel free to re-open :)