docs(kgo): add Konnect entities documentation

.github/styles/kong/dictionary.txt

@@ -230,6 +230,7 @@ ElastiCache
 elbs
 enablement
 enqueued
+enqueues
 enum
 env
 Equinix

app/_data/docs_nav_kgo_1.4.x.yml

@@ -103,6 +103,28 @@ items:
             url: /guides/upgrade/data-plane/rolling/
           - text: Blue / Green Deployment
             url: /guides/upgrade/data-plane/blue-green/
+      - text: Managing Konnect entities
+        items:
+          - text: Architecture overview
+            url: /guides/konnect-entities/architecture/
+          - text: Gateway Control Plane
+            url: /guides/konnect-entities/gatewaycontrolplane/
+          - text: Service and Route
+            url: /guides/konnect-entities/service-and-route/
+          - text: Consumer, Credentials and Consumer Groups
+            url: /guides/konnect-entities/consumer-and-consumergroup/
+          - text: Key and Key Set
+            url: /guides/konnect-entities/key-and-keyset/
+          - text: Upstream and Targets
+            url: /guides/konnect-entities/upstream-and-target/
+          - text: Certificate and CA Certificate
+            url: /guides/konnect-entities/certificate-and-cacertificate/
+          - text: Vault
+            url: /guides/konnect-entities/vault/
+          - text: Data Plane Client Certificate
+            url: /guides/konnect-entities/dpcertificate/
+          - text: Tagging and Labeling
+            url: /guides/konnect-entities/tagging-and-labeling/
   - title: Reference
     icon: /assets/images/icons/icn-magnifying-glass.svg
     items:

app/_includes/md/kgo/konnect-entities-prerequisites.md

@@ -0,0 +1,133 @@
+{% unless include.disable_accordian %}
+<details class="custom" markdown="1">
+<summary>
+<blockquote class="note">
+  <p style="cursor: pointer">Before you create any Konnect entity, make sure you've <u>installed {{site.kgo_product_name}} and created a valid KonnectAPIAuthConfiguration{% if include.with-control-plane %} and KonnectGatewayControlPlane{% endif %}</u> in your cluster.</p>
+</blockquote>
+</summary>
+
+## Prerequisites
+{% endunless %}
+
+{% include md/kgo/prerequisites.md disable_accordian=true version=page.version release=page.release kconf-crds=true %}
+
+### Create an access token in Konnect
+
+You may create either a Personal Access Token (PAT) or a Service Account Token (SAT) in Konnect. Please refer to the
+[Konnect authentication documentation](/konnect/api/#authentication) for more information. You will need this token
+to create a `KonnectAPIAuthConfiguration` object that will be used by the {{site.kgo_product_name}} to authenticate
+with Konnect APIs.
+
+### Create a Konnect API Auth Configuration
+
+Depending on your preferences, you might want to create a `KonnectAPIAuthConfiguration` object with the token specified
+directly in its spec or as a reference to a Kubernetes Secret. The `serverURL` field should be set to the Konnect API
+URL in a region where your Konnect account is located. Please refer to the [list of available API URLs](/konnect/network/)
+for more information.
+
+{% navtabs token %}
+{% navtab Directly in specification %}
+```yaml
+echo '
+kind: KonnectAPIAuthConfiguration
+apiVersion: konnect.konghq.com/v1alpha1
+metadata:
+  name: konnect-api-auth
+  namespace: default
+spec:
+  type: token
+  token: kpat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+  serverURL: eu.api.konghq.com
+' | kubectl apply -f -
+```
+{% endnavtab %}
+{% navtab Stored in a Secret %}
+Please note that the Secret must have the `konghq.com/credential: konnect` label to make the {{site.kgo_product_name}}
+reconcile it.
+
+```yaml
+echo '
+kind: KonnectAPIAuthConfiguration
+apiVersion: konnect.konghq.com/v1alpha1
+metadata:
+  name: konnect-api-auth
+  namespace: default
+spec:
+  type: secretRef
+  secretRef:
+    name: konnect-api-auth-secret
+  serverURL: eu.api.konghq.com
+---
+kind: Secret
+apiVersion: v1
+metadata:
+  name: konnect-api-auth-secret
+  namespace: default
+  labels:
+    konghq.com/credential: konnect
+stringData:
+  token: kpat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+' | kubectl apply -f -
+```
+{% endnavtab %}
+{% endnavtabs %}
+
+You can verify the `KonnectAPIAuthConfiguration` object was reconciled successfully by checking its status.
+
+```shell
+kubectl get konnectapiauthconfiguration konnect-api-auth
+```
+
+The output should look like this:
+
+```console
+NAME               VALID   ORGID                                  SERVERURL
+konnect-api-auth   True    <your-konnect-org-id>                  https://eu.api.konghq.tech
+```
+
+{% if include.with-control-plane %}
+### Create a Gateway Control Plane
+
+Creating the `KonnectGatewayControlPlane` object in your Kubernetes cluster will provision a Konnect Gateway
+Control Plane in your [Gateway Manager](/konnect/gateway-manager). The `KonnectGatewayControlPlane` CR
+[API](/gateway-operator/{{ page.release }}/reference/custom-resources/#konnectgatewaycontrolplane) allows you to
+explicitly set a type of the Gateway Control Plane, but if you don't specify it, the default type is
+a [Self-Managed Hybrid
+Gateway Control Plane](/konnect/gateway-manager/#kong-gateway-control-planes).
+
+You can create one by applying the following YAML manifest:
+
+```yaml
+echo '
+kind: KonnectGatewayControlPlane
+apiVersion: konnect.konghq.com/v1alpha1
+metadata:
+  name: gateway-control-plane
+  namespace: default
+spec:
+  name: gateway-control-plane # Name used to identify the Gateway Control Plane in Konnect
+  konnect:
+    authRef:
+      name: konnect-api-auth # Reference to the KonnectAPIAuthConfiguration object
+  ' | kubectl apply -f -
+```
+
+You can see the status of the Gateway Control Plane by running:
+
+```shell
+kubectl get konnectgatewaycontrolplanes.konnect.konghq.com gateway-control-plane
+```
+
+If the Gateway Control Plane is successfully created, you should see the following output:
+
+```shell
+NAME                    PROGRAMMED   ID                                     ORGID
+gateway-control-plane   True         <konnect-control-plane-id>             <your-konnect-ord-id>
+```
+
+Having that in place, you will be able to reference the `gateway-control-plane` in your Konnect entities as their parent.
+{% endif %}
+
+{% unless include.disable_accordian %}
+</details>
+{% endunless %}

app/_includes/md/kgo/prerequisites.md

@@ -2,7 +2,7 @@
 <details class="custom" markdown="1">
 <summary>
 <blockquote class="note">
-  <p style="cursor: pointer">Before you begin ensure that you have <u>installed the {{site.kgo_product_name}}</u> in your Kubernetes cluster {% if include.aiGateway %}with AI Gateway support enabled{% endif %}. {% if include.enterprise %}This guide requires an enterprise license.{% endif %}</p>
+  <p style="cursor: pointer">Before you begin ensure that you have <u>installed the {{site.kgo_product_name}}</u> in your Kubernetes cluster {% if include.aiGateway %}with AI Gateway support enabled{% endif %}{% if include.kconf-crds %}with Kong's Kubernetes Configuration CRDs enabled{% endif %}. {% if include.enterprise %}This guide requires an enterprise license.{% endif %}</p>
 </blockquote>
 </summary>
 
@@ -33,7 +33,7 @@ kubectl apply -f {{site.links.web}}/assets/gateway-operator/ai-gateway-crd.yaml
 
 ### Install {{ site.kgo_product_name }}
 
-{% include snippets/gateway-operator/install_with_helm.md version=include.version release=include.release %}
+{% include snippets/gateway-operator/install_with_helm.md version=include.version release=include.release kconf-crds=include.kconf-crds %}
 
 
 {%- if include.aiGateway %}

app/_includes/snippets/gateway-operator/install_with_helm.md

@@ -13,7 +13,7 @@ helm repo update kong
 Install {{ site.kgo_product_name }} with Helm:
 
 ```bash
-helm upgrade --install kgo kong/gateway-operator -n kong-system --create-namespace --set image.tag={{ kgo_version }}
+helm upgrade --install kgo kong/gateway-operator -n kong-system --create-namespace --set image.tag={{ kgo_version }} {{ if include.kconf-crds }}--set kubernetes-configuration-crds.enabled=true{{ endif }}
 ```
 
 You can wait for the operator to be ready using `kubectl wait`:

app/_src/gateway-operator/guides/konnect-entities/architecture.md

@@ -0,0 +1,124 @@
+---
+title: Architecture
+---
+
+In this guide you'll learn how your Kubernetes resources are synchronized against Konnect.
+
+## Overview
+
+{{site.kgo_product_name}} 1.4.0 introduced support for managing Konnect entities.
+It is designed to allow users drive their {{site.konnect_short_name}} configuration through Kubernetes [CRDs][k8s_crds].
+
+[k8s_crds]: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/
+
+{:.note}
+> **Note:** Konnect entities management is an opt-in feature. You must
+> enable it by setting `GATEWAY_OPERATOR_ENABLE_CONTROLLER_KONNECT` environment variable to `true`.
+
+At a high level {{site.kgo_product_name}}, watches for changes in the Kubernetes cluster and synchronizes them against {{site.konnect_product_name}}.
+
+Below diagram illustrates high level overview, how {{site.konnect_short_name}} configuration is synchronized from Kubernetes resources to {{site.konnect_short_name}}:
+
+<!--vale off-->
+{% mermaid %}
+flowchart BT
+
+    subgraph Kong Konnect
+        direction LR
+
+        KonnectAPI(<img src="/assets/images/logos/konglogo-gradient-secondary.svg" style="max-width:32px; display:block; margin:0 auto;" class="no-image-expand"/>Konnect APIs)
+    end
+
+    subgraph Kubernetes cluster
+        direction LR
+
+        KGO(<img src="/assets/images/logos/konglogo-gradient-secondary.svg" style="max-width:32px; display:block; margin:0 auto;" class="no-image-expand"/>Kong Gateway Operator)
+        K8sAPIServer(<img src="/assets/images/icons/third-party/kubernetes-logo.png" style="max-width:32px; display:block; margin:0 auto;" class="no-image-expand"/> API server)
+    end
+
+    KGO -.-> |configuration synchronization| KonnectAPI
+    K8sAPIServer -.-> |events| KGO
+{% endmermaid %}
+<!--vale on-->
+
+## How it works
+
+{{site.kgo_product_name}} watches for changes in the Kubernetes cluster and synchronizes them against {{site.konnect_short_name}}.
+
+The synchronization is performed in a loop, where the operator reconciles the state of the cluster with the state of {{site.konnect_short_name}}.
+
+The algorithm is as follows:
+
+- When a Kubernetes resource is created:
+  - The operator checks if it has references and whether they are valid, if not it assigns a failure condition to the resource.
+  - If the resource has references and they are valid, the operator calls the Konnect API's create method.
+    - If the creation was unsuccessful, the operator assigns a failure condition to the resource.
+    - If the creation was successful, the operator assigns the resource's ID, OrgID, ServerURL and status conditions.
+  - The operator enqueues the resource for update after the configured sync period passes.
+
+- When a Kubernetes resource is updated:
+  - The operator checks if the resource's spec, annotations or labels have changed.
+  - If the spec, annotations or labels have changed:
+    - The operator calls the Konnect API's update method.
+      - If the update was unsuccessful, the operator assigns a failure condition to the resource.
+      - If the update was successful, the operator waits for the configured sync period to pass.
+  - If the spec, annotations or labels have not changed:
+    - If sync period has not passed, the operator enqueues the resource for update.
+    - If sync period has passed, the operator calls the Konnect API's update method.
+      - If the update was unsuccessful, the operator assigns a failure condition to the resource.
+      - If the update was successful, the operator enqueues the resource for update.
+
+- When a Kubernetes resource is deleted:
+  - The operator calls the Konnect API's delete method.
+    - If the deletion was unsuccessful, the operator assigns a failure condition to the resource.
+    - If the deletion was successful, the operator removes the resource from the cluster.
+
+Below diagram illustrates the algorithm:
+
+<!--vale off-->
+{% mermaid %}
+flowchart TB
+
+classDef decision fill:#d0e1fb
+classDef start fill:#545454,stroke:none,color:#fff
+
+    k8sResourceCreated(Kubernetes resource created)
+    k8sResourceUpdated(Kubernetes resource updated)
+    rLoopStart[Operator reconciliation start]
+    failure[Assign object's status conditions to indicate failure]
+    resourceSpecChanged{Resource spec, annotations or labels changed?}
+    waitForSync["Wait until sync period passes (default 1m)
+    (Prevent API rate limiting)"]
+    createSuccess[Assign object's ID, OrgID, ServerURL and status conditions]
+    hasReferences{If object has references, are they all valid?}
+    isAlreadyCreated{Object already created?}
+    syncPeriodPassed[Sync period passed]
+    updateKonnectEntity[Call Konnect API's update]
+    wasUpdateSuccessful{Was update successful?}
+    wasCreateSuccessful{Was create successful?}
+    callCreate[Call Konnect API's create]
+
+    k8sResourceCreated --> rLoopStart
+    rLoopStart --> isAlreadyCreated
+    isAlreadyCreated -->|Yes| waitForSync
+    isAlreadyCreated -->|No| hasReferences
+    hasReferences -->|Yes| callCreate
+    hasReferences -->|No| failure
+    callCreate --> wasCreateSuccessful
+    wasCreateSuccessful -->|Yes| createSuccess
+    wasCreateSuccessful -->|No| failure
+    k8sResourceUpdated --> resourceSpecChanged
+    resourceSpecChanged -->|Yes| updateKonnectEntity
+    resourceSpecChanged -->|No| waitForSync
+    createSuccess --> waitForSync
+    waitForSync --> syncPeriodPassed
+    syncPeriodPassed --> updateKonnectEntity
+    updateKonnectEntity --> wasUpdateSuccessful
+    wasUpdateSuccessful -->|Yes| waitForSync
+    wasUpdateSuccessful -->|No| failure
+    failure -->rLoopStart
+
+class hasReferences,wasCreateSuccessful,wasUpdateSuccessful decision
+class k8sResourceCreated,k8sResourceUpdated start
+{% endmermaid %}
+<!--vale on-->