doc: RDN values and create-only attributes

Add notes which fields are the primary keys / RDN values (relative distinguised names) of objects. IPA does not support `modrdn` for servers, certificates, and DNS locations. That means the entries cannot be renamed and an RDN value identifies an entry. Also note that domain name and realm name cannot be modified by an update. Signed-off-by: Christian Heimes <[email protected]>
podengo-project · Nov 9, 2023 · f32b6bf · f32b6bf
1 parent c922620
commit f32b6bf
Show file tree

Hide file tree

Showing 2 changed files with 22 additions and 8 deletions.
diff --git a/public.openapi.json b/public.openapi.json
@@ -603,7 +603,7 @@
             "example": "O=DOMAIN.EXAMPLE, CN=Certificate Authority"
           },
           "nickname": {
-            "title": "Internal nick name in LDAP",
+            "title": "Internal nick name in LDAP (RDN cn)",
             "type": "string",
             "example": "DOMAIN.EXAMPLE CA"
           },
@@ -640,7 +640,8 @@
         },
         "x-rh-ipa-hcc": {
           "type": "defs"
-        }
+        },
+        "x-rh-rdn-value": "nickname"
       },
       "Domain": {
         "title": "Base type for domain objects",
@@ -683,6 +684,7 @@
         "x-rh-ipa-hcc": {
           "type": "defs"
         },
+        "x-rh-rdn-value": "domain_name",
         "example": {
           "description": "My awesome domain description.",
           "auto_enrollment_enabled": true,
@@ -823,6 +825,7 @@
           "name": "IPAServer",
           "type": "defs"
         },
+        "x-rh-rdn-value": "fqdn",
         "example": {
           "ca_server": true,
           "fqdn": "ipaserver.mydomain.example",
@@ -835,7 +838,7 @@
       },
       "DomainName": {
         "title": "Fully qualified domain name",
-        "description": "A name of a domain (all lower-case)",
+        "description": "A name of a domain (all lower-case). The domain name can only be set during initial registration and not be modified by updates.\n",
         "type": "string",
         "format": "idn-hostname",
         "maxLength": 253,
@@ -1329,7 +1332,8 @@
         },
         "x-rh-ipa-hcc": {
           "type": "defs"
-        }
+        },
+        "x-rh-rdn-value": "name"
       },
       "LocationName": {
         "title": "Location identifier (IPA location, AD site)",
@@ -1418,7 +1422,7 @@
       },
       "RealmName": {
         "title": "Kerberos realm name",
-        "description": "A Kerberos realm name (usually all upper-case domain name)",
+        "description": "A Kerberos realm name (usually all upper-case domain name). The realm can only be set during initial registration and not be modified by updates.\n",
         "type": "string",
         "format": "realm",
         "maxLength": 253,

diff --git a/public.openapi.yaml b/public.openapi.yaml
@@ -381,7 +381,7 @@ components:
                     format: cert-issuer
                     example: O=DOMAIN.EXAMPLE, CN=Certificate Authority
                 nickname:
-                    title: Internal nick name in LDAP
+                    title: Internal nick name in LDAP (RDN cn)
                     type: string
                     example: DOMAIN.EXAMPLE CA
                 not_after:
@@ -411,6 +411,7 @@ components:
                     example: O=DOMAIN.EXAMPLE, CN=Certificate Authority
             x-rh-ipa-hcc:
                 type: defs
+            x-rh-rdn-value: nickname
         Domain:
             title: Base type for domain objects
             description: A domain resource
@@ -442,6 +443,7 @@ components:
                     $ref: '#/components/schemas/DomainIpa'
             x-rh-ipa-hcc:
                 type: defs
+            x-rh-rdn-value: domain_name
             example:
                 description: My awesome domain description.
                 auto_enrollment_enabled: true
@@ -559,6 +561,7 @@ components:
             x-rh-ipa-hcc:
                 name: IPAServer
                 type: defs
+            x-rh-rdn-value: fqdn
             example:
                 ca_server: true
                 fqdn: ipaserver.mydomain.example
@@ -569,7 +572,10 @@ components:
                 subscription_manager_id: 03965a2c-bd24-11ed-968d-482ae3863d30
         DomainName:
             title: Fully qualified domain name
-            description: A name of a domain (all lower-case)
+            description: >
+                A name of a domain (all lower-case). The domain name can only
+                be set during initial registration and not be modified by
+                updates.
             type: string
             format: idn-hostname
             maxLength: 253
@@ -943,6 +949,7 @@ components:
                     type: string
             x-rh-ipa-hcc:
                 type: defs
+            x-rh-rdn-value: name
         LocationName:
             title: Location identifier (IPA location, AD site)
             description: A location identifier (lower-case DNS label)
@@ -1014,7 +1021,10 @@ components:
                 offset: 0
         RealmName:
             title: Kerberos realm name
-            description: A Kerberos realm name (usually all upper-case domain name)
+            description: >
+                A Kerberos realm name (usually all upper-case domain name).
+                The realm can only be set during initial registration and not
+                be modified by updates.
             type: string
             format: realm
             maxLength: 253