Create docs for upgrading to v4

[pingles]

There's been a number of breaking changes #435 #431 introduced recently.

Before releasing we'll need something in the upgrading doc and release notes to help people understand the changes. In particular, changes to when regexes are applied will affect running workloads.

[leosunmo]

From #435

@leosunmo what do you think? Could you prep some examples of how the namespace regex behaved before, and now, and what the implications are please?

Looking back at my original issue I can't think of a scenario where the "new" process would result in more permissive behaviour, but potentially where it is less permissive after the ARN resolver is added.

First, to recap and to get something started for the 4.0 Upgrade guide.
Using the following scenario from the original ticket:

# namespace
annotations:
  iam.amazonaws.com/permitted: .*workloads/.*

# Kiam Server
--role-base-arn=arn:aws:iam::1234567890:role/workloads/

# pod
annotations:
  iam.amazonaws.com/role: my-amazing-role

Old behaviour, where role ARN is NOT resolved before rules are evaluated

Fails, since my-amazing-role != .*workloads/.*:

failed assuming role "my-amazing-role": namespace policy expression '.*workloads/.*' forbids role 'my-amazing-role'

New behaviour, where the role is fully expanded/resolved before rules are evaluated.

Passes, since role = role-base-arn + pod annotation:

arn:aws:iam::1234567890:role/workloads/my-amazing-role == .*workloads/.*
Success!

---

A scenario that would pass evaluation using the old resolver logic:

# namespace
annotations:
  iam.amazonaws.com/permitted: ^red-role$

# Kiam Server
--role-base-arn=arn:aws:iam::1234567890:role/workloads/

# pod
annotations:
  iam.amazonaws.com/role: red-role

Not very realistic, or likely to actually affect anyone, but this would currently pass, but fail using the new evaluation implementation.

[leosunmo]

Something that will have more impact on behaviour and backwards compatibility is #328 / #329

[stefansedich]

#437 is also a breaking change.