docs: Add configuration docs for API restrictions

Co-authored-by: Sarah Corleissen <sarah.corleissen@isovalent.com>
Signed-off-by: Joe Stringer <joe@cilium.io>

Documentation/Makefile

@@ -63,7 +63,7 @@ codeowners.rst: $(ROOT_DIR)/CODEOWNERS
 .PHONY: update-codeowners
 update-codeowners: codeowners.rst
 
-check: builder-image update-cmdref update-helm-values update-codeowners ## Validate command and Helm references, as well as policy examples.
+check: builder-image api-flaggen update-cmdref update-helm-values update-codeowners ## Validate command and Helm references, as well as policy examples.
 	@$(ECHO_CHECK) cmdref
 	$(QUIET) ./check-cmdref.sh
 	@$(ECHO_CHECK) $(HELM_VALUES)
@@ -72,11 +72,20 @@ check: builder-image update-cmdref update-helm-values update-codeowners ## Valid
 	$(QUIET)$(DOCKER_RUN) ./check-examples.sh
 	@$(ECHO_CHECK) codeowners.rst
 	$(QUIET) ./check-codeowners.sh
+	@$(ECHO_CHECK) configuration/api-restrictions-table.rst
+	$(QUIET) ./check-flaggen.sh
 
 ifeq ($(V),0)
 SPHINX_OPTS += -q
 endif
 
+.PHONY: api-flaggen
+api-flaggen:
+	@$(ECHO_GEN) api-flags
+	$(QUIET)$(GO) run $(ROOT_DIR)/tools/api-flaggen \
+		2>/dev/null \
+		> configuration/api-restrictions-table.rst
+
 copy-api:
 	@$(ECHO_GEN)_api
 	$(QUIET)cp -r ../api/. _api

Documentation/check-flaggen.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+config_dir="${script_dir}/configuration"
+
+if ! git diff --quiet -- "${config_dir}" ; then
+    git --no-pager diff "${config_dir}"
+    echo "HINT: to fix this, run 'make -C Documentation api-flaggen'"
+    exit 1
+fi
+

Documentation/configuration/api-restrictions-table.rst

@@ -0,0 +1,127 @@
+.. <!-- This file was autogenerated via api-flaggen, do not edit manually-->
+
+Cilium Agent API
+================
+
+The following API flags are compatible with the ``cilium-agent`` flag
+``enable-cilium-api-server-access``.
+
+===================== ====================
+Flag Name             Description
+===================== ====================
+DeleteEndpointID      Deletes the endpoint specified by the ID. Deletion is
+                      imminent and atomic, if the deletion request is valid and
+                      the endpoint exists, deletion will occur even if errors are
+                      encountered in the process. If errors have been encountered,
+                      the code 202 will be returned, otherwise 200 on success. All
+                      resources associated with the endpoint will be freed and the
+                      workload represented by the endpoint will be disconnected.It
+                      will no longer be able to initiate or receive communications
+                      of any sort.
+DeleteFqdnCache       Deletes matching DNS lookups from the cache, optionally
+                      restricted by DNS name. The removed IP data will no longer
+                      be used in generated policies.
+DeleteIPAMIP          -
+DeletePolicy          -
+DeletePrefilter       -
+DeleteRecorderID      -
+DeleteServiceID       -
+GetBGPPeers           Retrieves current operational state of BGP peers created by
+                      Cilium BGP virtual router. This includes session state,
+                      uptime, information per address family, etc.
+GetCgroupDumpMetadata -
+GetClusterNodes       -
+GetConfig             Returns the configuration of the Cilium daemon.
+GetDebuginfo          -
+GetEndpoint           Retrieves a list of endpoints that have metadata matching
+                      the provided parameters, or all endpoints if no parameters
+                      provided.
+GetEndpointID         Returns endpoint information
+GetEndpointIDConfig   Retrieves the configuration of the specified endpoint.
+GetEndpointIDHealthz  -
+GetEndpointIDLabels   -
+GetEndpointIDLog      -
+GetFqdnCache          Retrieves the list of DNS lookups intercepted from
+                      endpoints, optionally filtered by DNS name, CIDR IP range or
+                      source.
+GetFqdnCacheID        Retrieves the list of DNS lookups intercepted from the
+                      specific endpoint, optionally filtered by endpoint id, DNS
+                      name, CIDR IP range or source.
+GetFqdnNames          Retrieves the list of DNS-related fields (names to poll,
+                      selectors and their corresponding regexes).
+GetHealthz            Returns health and status information of the Cilium daemon
+                      and related components such as the local container runtime,
+                      connected datastore, Kubernetes integration and Hubble.
+GetIP                 Retrieves a list of IPs with known associated information
+                      such as their identities, host addresses, Kubernetes pod
+                      names, etc. The list can optionally filtered by a CIDR IP
+                      range.
+GetIdentity           Retrieves a list of identities that have metadata matching
+                      the provided parameters, or all identities if no parameters
+                      are provided.
+GetIdentityEndpoints  -
+GetIdentityID         -
+GetLRP                -
+GetMap                -
+GetMapName            -
+GetMapNameEvents      -
+GetMetrics            -
+GetNodeIds            Retrieves a list of node IDs allocated by the agent and
+                      their associated node IP addresses.
+GetPolicy             Returns the entire policy tree with all children.
+GetPolicySelectors    -
+GetPrefilter          -
+GetRecorder           -
+GetRecorderID         -
+GetRecorderMasks      -
+GetService            -
+GetServiceID          -
+PatchConfig           Updates the daemon configuration by applying the provided
+                      ConfigurationMap and regenerates & recompiles all required
+                      datapath components.
+PatchEndpointID       Applies the endpoint change request to an existing endpoint
+PatchEndpointIDConfig Update the configuration of an existing endpoint and
+                      regenerates & recompiles the corresponding programs
+                      automatically.
+PatchEndpointIDLabels Sets labels associated with an endpoint. These can be user
+                      provided or derived from the orchestration system.
+PatchPrefilter        -
+PostIPAM              -
+PostIPAMIP            -
+PutEndpointID         Creates a new endpoint
+PutPolicy             -
+PutRecorderID         -
+PutServiceID          -
+===================== ====================
+
+Cilium Agent Clusterwide Health API
+===================================
+
+The following API flags are compatible with the ``cilium-agent`` flag
+``enable-cilium-health-api-server-access``.
+
+===================== ====================
+Flag Name             Description
+===================== ====================
+GetHealthz            Returns health and status information of the local node
+                      including load and uptime, as well as the status of related
+                      components including the Cilium daemon.
+GetStatus             Returns the connectivity status to all other cilium-health
+                      instances using interval-based probing.
+PutStatusProbe        Runs a synchronous probe to all other cilium-health
+                      instances and returns the connectivity status.
+===================== ====================
+
+Cilium Operator API
+===================
+
+The following API flags are compatible with the ``cilium-operator`` flag
+``enable-cilium-operator-server-access``.
+
+===================== ====================
+Flag Name             Description
+===================== ====================
+GetHealthz            This path will return the status of cilium operator
+                      instance.
+GetMetrics            -
+===================== ====================

Documentation/configuration/api-restrictions.rst

@@ -0,0 +1,37 @@
+.. only:: not (epub or latex or html)
+
+    WARNING: You are looking at unreleased Cilium documentation.
+    Please use the official rendered version released here:
+    https://docs.cilium.io
+
+*****************************
+Administrative API Enablement
+*****************************
+
+Cilium 1.14 introduced a new set of flags that you can use to selectively
+enable which API endpoints are exposed to clients. When an API client makes a
+request to an API endpoint that is administratively disabled, the server
+responds with an HTTP 403 Forbidden error.
+
+You can configure the option with a list of endpoints as described in the
+following sections, or by specifying an option with the ``*`` suffix. If ``*``
+is provided directly as a flag value, then all APIs are enabled. If there is
+text before the ``*``, then the API flag must start with that prefix in order
+for the flag to enable that option. For example, ``Get*`` enables all read-only
+"GET" APIs without enabling any write APIs.
+
+The cilium-agent relies on several of these APIs for its basic duties. In
+particular, disabling the following APIs will likely cause significant
+disruption to agent operations:
+
+- ``GetConfig``
+- ``GetHealthz``
+- ``PutEndpointID``
+- ``DeleteEndpointID``
+- ``PostIPAM``
+- ``DeleteIPAMIP``
+
+The following sections outline the flags for different Cilium binaries and the
+API endpoints that may be configured using those flags.
+
+.. include:: api-restrictions-table.rst

Documentation/configuration/index.rst

@@ -67,6 +67,7 @@ Core Agent
    :glob:
 
    api-rate-limiting
+   api-restrictions
    per-node-config
    sctp
    vlan-802.1q

Documentation/spelling_wordlist.txt

@@ -202,6 +202,7 @@ autoDirectNodeRoutes
 autoMount
 autoProtectPortRange
 autocompletion
+autogenerated
 autoload
 automount
 autoscaler
@@ -463,6 +464,7 @@ filenames
 filesystem
 filesystems
 firewalling
+flaggen
 followup
 foobar
 foundational