Add UPDATE_API_KNOWN_VIOLATIONS=true to Makefile.generated_files

One can run:
    make generated_files UPDATE_API_KNOWN_VIOLATIONS=true
to update the checked-in known API violation exceptions list.

Also updated README and the error message on how to resolve the
failure.

api/api-rules/README.md

@@ -1,9 +1,11 @@
-## Existing API Rule Violations
+# Existing API Rule Violations
 
 This folder contains the checked-in report file of known API rule violations.
 The file violation\_exceptions.list is used by Make rule during OpenAPI spec generation to make
 sure that no new API rule violation is introduced into our code base.
 
+## API Rule Violation Format
+
 The report file [violation\_exceptions.list](./violation_exceptions.list) is in format of:
 
  * ***API rule violation: \<RULE\>,\<PACKAGE\>,\<TYPE\>,\<FIELD\>***
@@ -12,11 +14,29 @@ e.g.
 
  * ***API rule violation: names_match,k8s.io/api/core/v1,Event,ReportingController***
 
+And the violation list is sorted alphabetically in each of the \<RULE\>, \<PACKAGE\>, \<TYPE\>, \<FIELD\> levels.
+
+## How to resolve API Rule Check Failure
+
 Make rule returns an error when the newly generated violation report differs from this
-checked-in violation report. If a new API rule violation is detected, please fix
-the API Go source file to pass the API rule check. **The entries in the checked-in
-violation report should only be removed when existing API rule violation is
-being fixed, but not added.**
+checked-in violation report.
+
+Our goal is that exceptions should never be added to this list, only fixed and removed.
+For new APIs, this is a hard requirement. For APIs that are e.g. being moved between
+versions or groups without other changes, it is OK for your API reviewer to make an
+exception.
+
+If you're removing violations from the exception list, or if you have good
+reasons to add new violations to this list, please update the file using:
+
+ - `make generated_files UPDATE_API_KNOWN_VIOLATIONS=true`
+
+It is up to API reviewers to review the list and make sure new APIs follow our API conventions.
+
+**NOTE**: please don't hide changes to this file in a "generated changes" commit, treat it as
+source code instead.
+
+## API Rules Being Enforced
 
 For more information about the API rules being checked, please refer to
 https://github.com/kubernetes/kube-openapi/tree/master/pkg/generators/rules

build/root/Makefile.generated_files

@@ -405,7 +405,15 @@ OPENAPI_OUTPUT_PKG := pkg/generated/openapi
 BOILERPLATE_FILENAME := vendor/k8s.io/code-generator/hack/boilerplate.go.txt
 REPORT_FILENAME := $(OUT_DIR)/violations.report
 KNOWN_VIOLATION_FILENAME := api/api-rules/violation_exceptions.list
-API_RULE_CHECK_FAILURE_MESSAGE := "Error: API rules check failed. Reported violations \"$(REPORT_FILENAME)\" differ from known violations \"$(KNOWN_VIOLATION_FILENAME)\". Please fix API source file if new violation is detected, or update known violations \"$(KNOWN_VIOLATION_FILENAME)\" if existing violation is being fixed. Please refer to api/api-rules/README.md and https://github.com/kubernetes/kube-openapi/tree/master/pkg/generators/rules for more information about the API rules being enforced."
+# When UPDATE_API_KNOWN_VIOLATIONS is set to be true, let the generator to write
+# updated API violations to the known API violation exceptions list.
+ifeq ($(UPDATE_API_KNOWN_VIOLATIONS),true)
+    REPORT_FILENAME:=$(KNOWN_VIOLATION_FILENAME)
+    # When UPDATE_API_KNOWN_VIOLATIONS is set to be true, touch the exceptions
+    # list so that the OPENAPI_OUTFILE target re-run instead of being cached.
+    $(shell touch $(KNOWN_VIOLATION_FILENAME))
+endif
+API_RULE_CHECK_FAILURE_MESSAGE := "ERROR: \n\t API rule check failed. Reported violations differ from known violations. Please read api/api-rules/README.md to resolve the failure. \n"
 
 # The tool used to generate open apis.
 OPENAPI_GEN := $(BIN_DIR)/openapi-gen
@@ -452,7 +460,7 @@ $(OPENAPI_OUTFILE): $(OPENAPI_GEN) $(KNOWN_VIOLATION_FILENAME)
 	    -r $(REPORT_FILENAME)                                                       \
 	    "$$@";                                                                      \
 	diff $(REPORT_FILENAME) $(KNOWN_VIOLATION_FILENAME) ||                          \
-	(echo $(API_RULE_CHECK_FAILURE_MESSAGE); exit 1)
+	(echo -e $(API_RULE_CHECK_FAILURE_MESSAGE); exit 1)
 
 
 # How to build the generator tool.  The deps for this are defined in