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

#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!

[azdagron]

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!).

[azdagron]

We should use "SPIRE Agent" instead of "SPIRE agent".

Suggested change

	This guide outlines the steps required to update your SPIRE agent IDs to conform to the enforced ID shape.
	This guide outlines the steps required to update your SPIRE Agent IDs to conform to the enforced ID shape.

[azdagron]

Yes, this has very much changed :) We introduced the warning in 1.2.1. We decided that we couldn't start enforcing until this migration guide was written. Once this guide has been authored and merged, the next minor release of SPIRE will start enforcing new agents to have that ID shape. The following minor version will start rejecting old agents.

[azdagron]

I think the most complete way to identify non-conforming IDs is with the spire-server agent list command. That will show all existing agents. It accepts a --output=json flag to output in JSON. The output could be piped into jq or something to get out all IDs.

You will also need to enumerate all registration entries to identify entries that are parented to the bad IDs. These registration entries will need to be duplicated and modified with the new agent ID. After the migration is successfully complete, the old entries can be removed.

[azdagron]

I think it's probably better to create new registrations, start transitioning agents, and then when all done, remove old registrations.

[azdagron]

This isn't so much re-registering agents as it is duplicating workload registrations parented directly to those agents.

[azdagron]

I think we'll also need a step here for slowly migrating agents over to the new IDs. In order to force an agent to re-attest, you'd need to use spire-server agent evict to evict the agent. This could be done slowly in the beginning to make sure the transition is ok.

[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 :)