diff --git a/app/_data/docs_nav_kgo_1.4.x.yml b/app/_data/docs_nav_kgo_1.4.x.yml index 4f23b6944880..91ef6d218c39 100644 --- a/app/_data/docs_nav_kgo_1.4.x.yml +++ b/app/_data/docs_nav_kgo_1.4.x.yml @@ -103,6 +103,10 @@ items: url: /guides/upgrade/data-plane/rolling/ - text: Blue / Green Deployment url: /guides/upgrade/data-plane/blue-green/ + - text: Konnect entities + items: + - text: Gateway Control Plane + url: /guides/konnect-entities/gatewaycontrolplane/ - title: Reference icon: /assets/images/icons/icn-magnifying-glass.svg items: diff --git a/app/_includes/md/kgo/konnect-entities-prerequisites.md b/app/_includes/md/kgo/konnect-entities-prerequisites.md new file mode 100644 index 000000000000..6c8bf2a3dab2 --- /dev/null +++ b/app/_includes/md/kgo/konnect-entities-prerequisites.md @@ -0,0 +1,90 @@ +{% unless include.disable_accordian %} +
+ +
+

Before you create any Konnect entity, make sure you've installed {{site.kgo_product_name}} and created a valid KonnectAPIAuthConfiguration in your cluster.

+
+ + +## 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 `KonnectAPIAuthConfiguration` object + +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 https://eu.api.konghq.tech +``` + +{% unless include.disable_accordian %} +
+{% endunless %} diff --git a/app/_includes/md/kgo/prerequisites.md b/app/_includes/md/kgo/prerequisites.md index 471d44f02912..6f001d4c51cc 100644 --- a/app/_includes/md/kgo/prerequisites.md +++ b/app/_includes/md/kgo/prerequisites.md @@ -2,7 +2,7 @@
-

Before you begin ensure that you have installed the {{site.kgo_product_name}} in your Kubernetes cluster {% if include.aiGateway %}with AI Gateway support enabled{% endif %}. {% if include.enterprise %}This guide requires an enterprise license.{% endif %}

+

Before you begin ensure that you have installed the {{site.kgo_product_name}} 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 %}

 @@ -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 %} diff --git a/app/_includes/snippets/gateway-operator/install_with_helm.md b/app/_includes/snippets/gateway-operator/install_with_helm.md index db1866435096..c1058105cab5 100644 --- a/app/_includes/snippets/gateway-operator/install_with_helm.md +++ b/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`: diff --git a/app/_src/gateway-operator/guides/konnect-entities/gatewaycontrolplane.md b/app/_src/gateway-operator/guides/konnect-entities/gatewaycontrolplane.md new file mode 100644 index 000000000000..71749657aba2 --- /dev/null +++ b/app/_src/gateway-operator/guides/konnect-entities/gatewaycontrolplane.md @@ -0,0 +1,142 @@ +--- +title: Gateway Control Plane +--- + +In this guide you'll learn how to use the `KonnectGatewayControlPlane` custom resource to +manage [Konnect Gateway Control +Planes](/konnect/gateway-manager/#control-planes) natively from your Kubernetes cluster. + +{% include md/kgo/konnect-entities-prerequisites.md disable_accordian=false version=page.version release=page.release %} + +## Creating a Self-Managed Hybrid 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 +``` + +## Creating a Control Plane Group + +Gateway Manager allows you to group multiple Gateway Control Planes. You can create +a [Control Plane Group](/konnect/gateway-manager/#control-plane-groups) by setting the `cluster_type` +field in the `spec` section of the `KonnectGatewayControlPlane` object to `CLUSTER_TYPE_CONTROL_PLANE_GROUP`. + +```yaml +echo ' +kind: KonnectGatewayControlPlane +apiVersion: konnect.konghq.com/v1alpha1 +metadata: + name: control-plane-group + namespace: default +spec: + name: control-plane-group # Name used to identify the Gateway Control Plane in Konnect + cluster_type: CLUSTER_TYPE_CONTROL_PLANE_GROUP # Type of the Gateway Control Plane + 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 konnectgatewaycontrolplane control-plane-group +``` + +If the Control Plane Group is successfully created, you should see the following output: + +```shell +NAME PROGRAMMED ID ORGID +control-plane-group True +``` + +### Adding a Gateway Control Plane to a Control Plane Group + +To assign Gateway Control Planes to a Control Plane Group, you need to specify the `members` field in the `spec` section of the `KonnectGatewayControlPlane` object. + +```yaml +echo ' +kind: KonnectGatewayControlPlane +apiVersion: konnect.konghq.com/v1alpha1 +metadata: + name: control-plane-group + namespace: default +spec: + name: control-plane-group # Name used to identify the Gateway Control Plane in Konnect + cluster_type: CLUSTER_TYPE_CONTROL_PLANE_GROUP # Type of the Gateway Control Plane + members: + - name: gateway-control-plane # Reference to the KonnectGatewayControlPlane object + konnect: + authRef: + name: konnect-api-auth # Reference to the KonnectAPIAuthConfiguration object + ' | kubectl apply -f - +``` + +You can check in your Gateway Manager to see if the Gateway Control Plane was successfully added to the Control Plane Group. + +## Creating a Kubernetes Ingress Controller Control Plane + +To create a [Kubernetes Ingress Controller Control Plane](/konnect/gateway-manager/kic/), you need to specify the +`cluster_type` field in the `spec` section of +the `KonnectGatewayControlPlane` object. + +```yaml +echo ' +kind: KonnectGatewayControlPlane +apiVersion: konnect.konghq.com/v1alpha1 +metadata: + name: kic-control-plane + namespace: default +spec: + name: kic-control-plane # Name used to identify the Gateway Control Plane in Konnect + cluster_type: CLUSTER_TYPE_K8S_INGRESS_CONTROLLER # Type of the Gateway Control Plane + 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 konnectgatewaycontrolplane kic-control-plane +``` + +If the Control Plane is successfully created, you should see the following output: + +```shell +NAME PROGRAMMED ID ORGID +kic-control-plane True +```