From fcb7c59436584ac8d75bd50b195fa5eb8e57e6f9 Mon Sep 17 00:00:00 2001
From: Trevor Knottnerus <tknott@amazon.com>
Date: Fri, 29 May 2026 14:51:21 -0700
Subject: [PATCH] Add resource-level note to DocumentationConfig

Adds a `note` field to ResourceDocsConfig that allows service controllers
to document special considerations for a resource via documentation.yaml.
The note is exposed through a CRD.Note() method for downstream consumers.
---
 pkg/config/documentation.go                   |  3 +++
 pkg/model/crd.go                              | 13 +++++++++
 pkg/model/field_test.go                       | 27 +++++++++++++++++++
 .../apis/eks/0000-00-00/documentation.yaml    |  3 +++
 4 files changed, 46 insertions(+)

diff --git a/pkg/config/documentation.go b/pkg/config/documentation.go
index e721e3c6..1b8e8404 100644
--- a/pkg/config/documentation.go
+++ b/pkg/config/documentation.go
@@ -15,6 +15,9 @@ type DocumentationConfig struct {
 // ResourceDocsConfig represents the configuration for the documentation
 // overrides of a single resource
 type ResourceDocsConfig struct {
+	// Note specifies a resource-level documentation note that describes
+	// special considerations for the resource
+	Note *string `json:"note,omitempty"`
 	Fields map[string]*FieldDocsConfig `json:"fields,omitempty"`
 }
 
diff --git a/pkg/model/crd.go b/pkg/model/crd.go
index 82230f68..5eb5e072 100644
--- a/pkg/model/crd.go
+++ b/pkg/model/crd.go
@@ -140,6 +140,19 @@ func (r *CRD) Documentation() string {
 	return docString
 }
 
+// Note returns the resource-level documentation note if one is configured,
+// otherwise returns an empty string.
+func (r *CRD) Note() string {
+	if r.docCfg == nil {
+		return ""
+	}
+	resourceConfig, exists := r.docCfg.Resources[r.Names.Camel]
+	if !exists || resourceConfig.Note == nil {
+		return ""
+	}
+	return *resourceConfig.Note
+}
+
 // HasShapeAsMember returns true if the supplied Shape name appears in *any*
 // payload shape of *any* Operation for the resource. It recurses down through
 // the resource's Operation Input and Output shapes and their member shapes
diff --git a/pkg/model/field_test.go b/pkg/model/field_test.go
index 4089bf63..0fdacac7 100644
--- a/pkg/model/field_test.go
+++ b/pkg/model/field_test.go
@@ -73,6 +73,33 @@ func TestFieldDocumentation(t *testing.T) {
 
 }
 
+func TestResourceNote(t *testing.T) {
+	require := require.New(t)
+
+	g := testutil.NewModelForServiceWithOptions(t, "eks",
+		&testutil.TestingModelOptions{
+			GeneratorConfigFile:     "generator.yaml",
+			DocumentationConfigFile: "documentation.yaml",
+		},
+	)
+
+	crds, err := g.GetCRDs()
+	require.Nil(err)
+
+	crd := getCRDByName("Cluster", crds)
+	require.NotNil(crd)
+
+	require.Equal(
+		"This resource does not support direct updates to the Kubernetes version.\nUse the UpdateClusterVersion API to upgrade.\n",
+		crd.Note(),
+	)
+
+	// A resource without a note should return empty string
+	addonCRD := getCRDByName("AddOn", crds)
+	require.NotNil(addonCRD)
+	require.Equal("", addonCRD.Note())
+}
+
 func TestMemberFields(t *testing.T) {
 	assert := assert.New(t)
 	require := require.New(t)
diff --git a/pkg/testdata/models/apis/eks/0000-00-00/documentation.yaml b/pkg/testdata/models/apis/eks/0000-00-00/documentation.yaml
index 4d1d9e82..6b6373c6 100644
--- a/pkg/testdata/models/apis/eks/0000-00-00/documentation.yaml
+++ b/pkg/testdata/models/apis/eks/0000-00-00/documentation.yaml
@@ -1,5 +1,8 @@
 resources:
   Cluster:
+    note: |
+      This resource does not support direct updates to the Kubernetes version.
+      Use the UpdateClusterVersion API to upgrade.
     fields:
       RoleARN:
         append: |