DM-45858: Document future CRD changes

crds/ingress.yaml

@@ -96,10 +96,10 @@ spec:
                         scopes:
                           type: array
                           description: >-
-                            Scopes to include in the delegated token if
-                            they are available. These scopes are not
-                            required to access the service; to make them
-                            required, include them in spec.scopes as well.
+                            Scopes to include in the delegated token if they
+                            are available. These scopes are not required to
+                            access the service; to make them required, include
+                            them in spec.scopes as well.
                           items:
                             type: string
                         service:
@@ -114,9 +114,9 @@ spec:
                     minimumLifetime:
                       type: integer
                       description: >-
-                        Minimum lifetime of delegated token in seconds. If
-                        the user's token has less than that time
-                        remaining, force them to reauthenticate.
+                        Minimum lifetime of delegated token in seconds. If the
+                        user's token has less than that time remaining, force
+                        them to reauthenticate.
                     useAuthorization:
                       type: boolean
                       description: >-
@@ -136,16 +136,12 @@ spec:
                 replace403:
                   type: boolean
                   description: >-
-                    Whether to replace 403 responses with a custom 403
-                    response from Gafaelfawr that disables caching and
-                    includes authorization-related errors in the
-                    `WWW-Authenticate` header.
+                    Obsolete setting. No longer has any effect.
                 scopes:
                   type: object
                   description: >-
-                    The token scope or scopes required to access this
-                    service.  May be omitted if the service allows
-                    anonymous access.
+                    The token scope or scopes required to access this service.
+                    May be omitted if the service allows anonymous access.
                   properties:
                     any:
                       type: array

docs/dev/index.rst

@@ -17,6 +17,7 @@ The Gafaelfawr code structure follows the guidelines in :sqr:`072`.
    userinfo
    scopes
    logging
+   kubernetes
 
 .. toctree::
    :caption: Guides

docs/dev/kubernetes.rst

@@ -0,0 +1,31 @@
+####################
+Kubernetes resources
+####################
+
+Gafaelfawr uses Kopf_ as the framework for its Kubernetes operators.
+Currently, the only version of both ``GafaelfawrIngress`` and ``GafaelfawrServiceToken`` is ``v1alpha1``.
+The CRDs are in the :file:`crds` directory at the root of the Gafaelfawr repository and in the :file:`applications/gafaelfawr/crds` directory in Phalanx.
+The latter are the versions of the CRDs installed by the chart, and should be a copy of the versions from the latest released version of Gafaelfawr.
+
+Future CRD changes
+==================
+
+Unfortunately, Kopf currently `doesn't support conversion webhooks <https://github.com/nolar/kopf/issues/956>`__, so there is no simple way to make backward-incompatible changes to the CRDs.
+For now, all changes to the CRDs have to be backward compatible, which means not removing any field and making all new fields optional.
+
+The following desirable changes to the existing object schemas are blocked on finding a way to properly follow the `CRD update process <https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/>`__.
+
+Changes to ``GafaelfawrIngress``
+--------------------------------
+
+- Make ``config.service`` mandatory and remove ``config.delegate.internal.service``.
+- Delete the ``config.rewrite403`` field.
+
+There will likely also be changes needed to support multiple domains and cross-domain authentication, but those have not yet been specified.
+
+Changes to ``GafaelfawrServiceToken``
+-------------------------------------
+
+- Support a list of tokens to create, each of which become fields in the generated ``Secret``.
+- Support generating the necessary tokens for `mobu <https://mobu.lsst.io/>`__ and `noteburst <https://noteburst.lsst.io/>`__, which may require multiple users with metadata generated from a template and an algorithm.
+  The goal would be to remove their need to have ``admin:token`` permissions and instead pre-generate all of their tokens.