From de0a7b0e06243850bf07505454711ad7592534b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Grzegorz=20Burzy=C5=84ski?= Date: Wed, 30 Oct 2024 17:15:32 +0100 Subject: [PATCH] docs(kgo): add Konnect entities documentation (#8084) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(kgo): prepare v1.4.x * docs(kgo): add intial Konnect entities documentation * docs(kgo): add Service and Route Konnect entities guide * docs(kgo): add Consumer, Credentials and ConsumerGroup Konnect entities guide * docs(kgo): add Key and KeySet Konnect entities guide * docs(kgo): add Upstream and Targets Konnect entities guide * docs(kgo): add Konnect entities tagging and labeling guide * Apply suggestions from code review Co-authored-by: Patryk Małek * docs(kgo): add Konnect entities architecture overview section * docs(kgo): add Certificate and CA Certificate Konnect entities guide * docs(kgo): add Vault Konnect entity guide * docs(kgo): add DP Client Certificate entity guide * docs(kgo): add more information about Konnect related fields * add include snippet for checking conditions * Apply suggestions from code review Co-authored-by: Angel * Apply suggestions from code review Co-authored-by: Angel * convert headers to lowercase and remove changelog --------- Co-authored-by: Patryk Małek Co-authored-by: Angel --- .github/styles/kong/dictionary.txt | 1 + app/_data/docs_nav_kgo_1.4.x.yml | 22 +++ app/_includes/md/kgo/check-condition.md | 24 +++ .../md/kgo/konnect-entities-prerequisites.md | 133 +++++++++++++ app/_includes/md/kgo/prerequisites.md | 4 +- .../gateway-operator/install_with_helm.md | 2 +- .../guides/konnect-entities/architecture.md | 183 ++++++++++++++++++ .../certificate-and-cacertificate.md | 143 ++++++++++++++ .../consumer-and-consumergroup.md | 138 +++++++++++++ .../guides/konnect-entities/dpcertificate.md | 54 ++++++ .../konnect-entities/gatewaycontrolplane.md | 142 ++++++++++++++ .../guides/konnect-entities/key-and-keyset.md | 158 +++++++++++++++ .../konnect-entities/service-and-route.md | 110 +++++++++++ .../konnect-entities/tagging-and-labeling.md | 80 ++++++++ .../konnect-entities/upstream-and-target.md | 93 +++++++++ .../guides/konnect-entities/vault.md | 58 ++++++ 16 files changed, 1342 insertions(+), 3 deletions(-) create mode 100644 app/_includes/md/kgo/check-condition.md create mode 100644 app/_includes/md/kgo/konnect-entities-prerequisites.md create mode 100644 app/_src/gateway-operator/guides/konnect-entities/architecture.md create mode 100644 app/_src/gateway-operator/guides/konnect-entities/certificate-and-cacertificate.md create mode 100644 app/_src/gateway-operator/guides/konnect-entities/consumer-and-consumergroup.md create mode 100644 app/_src/gateway-operator/guides/konnect-entities/dpcertificate.md create mode 100644 app/_src/gateway-operator/guides/konnect-entities/gatewaycontrolplane.md create mode 100644 app/_src/gateway-operator/guides/konnect-entities/key-and-keyset.md create mode 100644 app/_src/gateway-operator/guides/konnect-entities/service-and-route.md create mode 100644 app/_src/gateway-operator/guides/konnect-entities/tagging-and-labeling.md create mode 100644 app/_src/gateway-operator/guides/konnect-entities/upstream-and-target.md create mode 100644 app/_src/gateway-operator/guides/konnect-entities/vault.md diff --git a/.github/styles/kong/dictionary.txt b/.github/styles/kong/dictionary.txt index cac759824377..9bf3ce88cdd1 100644 --- a/.github/styles/kong/dictionary.txt +++ b/.github/styles/kong/dictionary.txt @@ -230,6 +230,7 @@ ElastiCache elbs enablement enqueued +enqueues enum env Equinix diff --git a/app/_data/docs_nav_kgo_1.4.x.yml b/app/_data/docs_nav_kgo_1.4.x.yml index 3d69bdad0204..9d2d63deacd1 100644 --- a/app/_data/docs_nav_kgo_1.4.x.yml +++ b/app/_data/docs_nav_kgo_1.4.x.yml @@ -107,6 +107,28 @@ items: url: /guides/upgrade/data-plane/blue-green/ - text: Kong Custom Plugin Distribution url: guides/plugin-distribution/ + - 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: diff --git a/app/_includes/md/kgo/check-condition.md b/app/_includes/md/kgo/check-condition.md new file mode 100644 index 000000000000..db54ba64a2e0 --- /dev/null +++ b/app/_includes/md/kgo/check-condition.md @@ -0,0 +1,24 @@ +{% assign name = include.name %} +{% assign kind = include.kind %} +{% assign conditionType = include.conditionType | default: "Programmed" %} +{% assign reason = include.reason | default: "Programmed" %} +{% assign generation = include.generation | default: 1 %} + +{% unless include.disableDescription %} +You can verify the `{{ kind }}` was reconciled successfully by checking its `{{ conditionType }}` condition. +{% endunless %} + +```shell +kubectl get {{ kind | downcase }} {{ name }} -o=jsonpath='{.status.conditions[?(@.type=="{{ conditionType }}")]}' | jq +``` + +The output should look similar to this: + +```console +{ + "observedGeneration": {{ generation }}, + "reason": "{{ reason }}", + "status": "True", + "type": "{{ conditionType }}" +} +``` 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..5c1d00c419ac --- /dev/null +++ b/app/_includes/md/kgo/konnect-entities-prerequisites.md @@ -0,0 +1,133 @@ +{% unless include.disable_accordian %} +
+ +
+

Before you create any Konnect entity, make sure you've installed {{site.kgo_product_name}} and created a valid `KonnectAPIAuthConfiguration` {% if include.with-control-plane %} and `KonnectGatewayControlPlane`{% endif %} 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 {{site.konnect_product_name}} API auth configuration + +Depending on your preferences, you can 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 {{site.konnect_product_name}} 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 +``` + +{% if include.with-control-plane %} +### Create a {{site.base_gateway}} control plane + +Creating the `KonnectGatewayControlPlane` object in your Kubernetes cluster will provision a {{site.konnect_product_name}} 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 {{site.base_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 +``` + +Having that in place, you will be able to reference the `gateway-control-plane` in your {{site.konnect_product_name}} entities as their parent. +{% endif %} + +{% unless include.disable_accordian %} +
+{% endunless %} diff --git a/app/_includes/md/kgo/prerequisites.md b/app/_includes/md/kgo/prerequisites.md index ecdc11b37481..8ab7772417d7 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.kongplugininstallation %} with KongPluginInstallation 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.kongplugininstallation %} with KongPluginInstallation 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/architecture.md b/app/_src/gateway-operator/guides/konnect-entities/architecture.md new file mode 100644 index 000000000000..bf99409526a4 --- /dev/null +++ b/app/_src/gateway-operator/guides/konnect-entities/architecture.md @@ -0,0 +1,183 @@ +--- +title: Architecture +--- + +In this guide you'll learn how your Kubernetes resources are synchronized against {{site.konnect_product_name}}. + +## Overview + +{{site.kgo_product_name}} 1.4.0 introduced support for managing {{site.konnect_product_name}} 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:** {{site.konnect_product_name}} 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}}: + + +{% mermaid %} +flowchart BT + + subgraph Kong Konnect + direction LR + + KonnectAPI(Konnect APIs) + end + + subgraph Kubernetes cluster + direction LR + + KGO(Kong Gateway Operator) + K8sAPIServer( API server) + end + + KGO -.-> |configuration synchronization| KonnectAPI + K8sAPIServer -.-> |events| KGO +{% endmermaid %} + + +## 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: + + +{% 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 %} + + +## Kubernetes resources + +Each Kubernetes resource that is mapped to a {{site.konnect_short_name}} entity has several fields that indicate its status in {{site.konnect_short_name}}. + +### Konnect native objects + +Objects that are native to {{site.konnect_short_name}} - they exist only in {{site.konnect_short_name}} - have the following `status` fields: + +- `id` is the unique identifier of the Konnect entity as assigned by {{site.konnect_product_name}} API. If it's unset (empty string), it means the {{site.konnect_product_name}} entity hasn't been created yet. +- `serverURL` is the URL of the {{site.konnect_product_name}} server in which the entity exists. +- `organizationID` is ID of {{site.konnect_product_name}} Org that this entity has been created in. + +You can observe these fields by running: + +```bash +kubectl get -o yaml | yq '.status' +``` + +You should see the following output: + +```yaml +conditions: + ... +id: 7dcf6756-b2e7-4067-a19b-111111111111 +organizationID: 5ca26716-02f7-4430-9117-111111111111 +serverURL: https://eu.api.konghq.com +``` + +These objects are defined under `konnect.konghq.com` API group. + +### Objects configuring {{site.base_gateway}} + +Some objects can be used to configure {{site.base_gateway}} and are not native to {{site.konnect_short_name}}. +These are for example `KongConsumer`, `KongService`, `KongRoute` and `KongPlugin`. They are defined under `configuration.konghq.com` API group. + +They can also be used in other contexts like for instance: be used for reconciliation with {{site.kic_product_name}}. + +These objects have their {{site.konnect_short_name}} status related fields nested under `konnect` field. These fields are: + +- `controlPlaneID` is the ID of the Control Plane this entity is associated with. +- `id` is the unique identifier of the Konnect entity as assigned by {{site.konnect_product_name}} API. If it's unset (empty string), it means the {{site.konnect_product_name}} entity hasn't been created yet. +- `serverURL` is the URL of the {{site.konnect_product_name}} server in which the entity exists. +- `organizationID` is ID of {{site.konnect_product_name}} Org that this entity has been created in. + +You can observe these fields by running: + +```bash +kubectl get -o yaml | yq '.status.konnect' +``` + +You should see the following output: + +```yaml +controlPlaneID: 7dcf6756-b2e7-4067-a19b-111111111111 +id: 7dcf6756-b2e7-4067-a19b-111111111111 +organizationID: 5ca26716-02f7-4430-9117-111111111111 +serverURL: https://eu.api.konghq.com +``` diff --git a/app/_src/gateway-operator/guides/konnect-entities/certificate-and-cacertificate.md b/app/_src/gateway-operator/guides/konnect-entities/certificate-and-cacertificate.md new file mode 100644 index 000000000000..774d1b8ea33a --- /dev/null +++ b/app/_src/gateway-operator/guides/konnect-entities/certificate-and-cacertificate.md @@ -0,0 +1,143 @@ +--- +title: Certificate and CA Certificate +--- + +In this guide you'll learn how to use the `KongCertificate` and `KongCACertificate` custom resources to +manage Konnect [Certificates](/konnect/gateway-manager/configuration/#certificates) +and CA Certificates natively from your Kubernetes cluster. + +{% include md/kgo/konnect-entities-prerequisites.md disable_accordian=false version=page.version release=page.release +with-control-plane=true %} + +## Create a certificate + +Creating the `KongCertificate` object in your Kubernetes cluster will provision a Konnect Certificate in +your [Gateway Manager](/konnect/gateway-manager). +You can refer to the CR [API](/gateway-operator/{{ page.release }}/reference/custom-resources/#kongcertificate) +to see all the available fields. + +Your `KongCertificate` must be associated with a `KonnectGatewayControlPlane` object that you've created in your +cluster. +It will make it part of the Gateway control plane's configuration. + +You can create a `KongCertificate` by applying the following YAML manifest: + +```yaml +echo ' +kind: KongCertificate +apiVersion: configuration.konghq.com/v1alpha1 +metadata: + name: cert + namespace: default +spec: + controlPlaneRef: + type: konnectNamespacedRef # This indicates that an in cluster reference is used + konnectNamespacedRef: + name: gateway-control-plane # Reference to the KonnectGatewayControlPlane object + cert: | # Sample certificate in PEM format, replace with your own + -----BEGIN CERTIFICATE----- + MIIB4TCCAYugAwIBAgIUAenxUyPjkSLCe2BQXoBMBacqgLowDQYJKoZIhvcNAQEL + BQAwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM + GEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDAeFw0yNDEwMjgyMDA3NDlaFw0zNDEw + MjYyMDA3NDlaMEUxCzAJBgNVBAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEw + HwYDVQQKDBhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQwXDANBgkqhkiG9w0BAQEF + AANLADBIAkEAyzipjrbAaLO/yPg7lL1dLWzhqNdc3S4YNR7f1RG9whWhbsPE2z42 + e6WGFf9hggP6xjG4qbU8jFVczpd1UPwGbQIDAQABo1MwUTAdBgNVHQ4EFgQUkPPB + ghj+iHOHAKJlC1gLbKT/ZHQwHwYDVR0jBBgwFoAUkPPBghj+iHOHAKJlC1gLbKT/ + ZHQwDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAANBALfy49GvA2ld+u+G + Koxa8kCt7uywoqu0hfbBfUT4HqmXPvsuhz8RinE5ltxId108vtDNlD/+bKl+N5Ub + qKjBs0k= + -----END CERTIFICATE----- + key: | # Sample private key in PEM format, replace with your own + -----BEGIN PRIVATE KEY----- + MIIBVAIBADANBgkqhkiG9w0BAQEFAASCAT4wggE6AgEAAkEAyzipjrbAaLO/yPg7 + lL1dLWzhqNdc3S4YNR7f1RG9whWhbsPE2z42e6WGFf9hggP6xjG4qbU8jFVczpd1 + UPwGbQIDAQABAkB4pTPsOMxznDrAWbYtcFovzJMPRIOp/2J5rtGdUcIAxP2rsdqh + Y1Nj2MV91UPsWjM0OpTD694T5mVR92oTUIvVAiEA7D1L8dCNc4pwZD7tpNLhZVh9 + BhCHPVVQ2RUwBype4FsCIQDcOFV7eD6LWTGLQfCcATr4qYLQ96Xu84F/CyqRIXvu + 1wIhAM3glYDFuaBJs60JUl1kEl4aAcr5OILxCSZGWrbD7C8lAiBtERF1JyaCyVf6 + SlwqR4m3YezCJgTuhXdbPmKEonrI3QIgIh52IOxTS7+ETXY1JjbouTR5irPEWgTM + +qqDoIn8JJI= + -----END PRIVATE KEY----- + ' | kubectl apply -f - +``` + +{% include md/kgo/check-condition.md name='cert' kind='KongCertificate' %} + +At this point, you should see the certificate in the Gateway Manager UI. + +### Assign an SNI to the certificate + +You can assign multiple SNIs to a `KongCertificate`. To do so, you need to create a `KongSNI` object and associate it +with +the `KongCertificate`. Please refer to the CR [API](/gateway-operator/{{ page.release +}}/reference/custom-resources/#kongsni) +to see all the available fields. + +You can create a `KongSNI` by applying the following YAML manifest: + +```yaml +echo ' +apiVersion: configuration.konghq.com/v1alpha1 +kind: KongSNI +metadata: + name: example-sni + namespace: default +spec: + certificateRef: + name: cert # Reference to the KongCertificate object + name: "sni.example.com" + ' | kubectl apply -f - +``` + +You can ensure the `KongCertificate` reference is valid by checking the `KongSNI`'s `KongCertificateRefValid` condition. + +{% include md/kgo/check-condition.md name='example-sni' kind='KongSNI' conditionType='KongCertificateRefValid' reason='Valid' disableDescription=true %} + +{% include md/kgo/check-condition.md name='example-sni' kind='KongSNI' %} + +At this point, you should see the SNI in the Certificate's SNIs in the Gateway Manager UI. + +## Create a CA Certificate + +Creating the `KongCACertificate` object in your Kubernetes cluster will provision a Konnect CA Certificate in +your [Gateway Manager](/konnect/gateway-manager). You can refer to the CR [API](/gateway-operator/{{ page.release +}}/reference/custom-resources/#kongcacertificate) to see all the available fields. + +Your `KongCACertificate` must be associated with a `KonnectGatewayControlPlane` object that you've created in your +cluster. + +You can create a `KongCACertificate` by applying the following YAML manifest: + +```yaml +echo ' +kind: KongCACertificate +apiVersion: configuration.konghq.com/v1alpha1 +metadata: + name: ca-cert + namespace: default +spec: + controlPlaneRef: + type: konnectNamespacedRef # This indicates that an in cluster reference is used + konnectNamespacedRef: + name: gateway-control-plane # Reference to the KonnectGatewayControlPlane object + cert: | # Sample CA certificate in PEM format, replace with your own + -----BEGIN CERTIFICATE----- + MIIB4TCCAYugAwIBAgIUAenxUyPjkSLCe2BQXoBMBacqgLowDQYJKoZIhvcNAQEL + BQAwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM + GEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDAeFw0yNDEwMjgyMDA3NDlaFw0zNDEw + MjYyMDA3NDlaMEUxCzAJBgNVBAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEw + HwYDVQQKDBhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQwXDANBgkqhkiG9w0BAQEF + AANLADBIAkEAyzipjrbAaLO/yPg7lL1dLWzhqNdc3S4YNR7f1RG9whWhbsPE2z42 + e6WGFf9hggP6xjG4qbU8jFVczpd1UPwGbQIDAQABo1MwUTAdBgNVHQ4EFgQUkPPB + ghj+iHOHAKJlC1gLbKT/ZHQwHwYDVR0jBBgwFoAUkPPBghj+iHOHAKJlC1gLbKT/ + ZHQwDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAANBALfy49GvA2ld+u+G + Koxa8kCt7uywoqu0hfbBfUT4HqmXPvsuhz8RinE5ltxId108vtDNlD/+bKl+N5Ub + qKjBs0k= + -----END CERTIFICATE----- +' | kubectl apply -f - +``` + +{% include md/kgo/check-condition.md name='ca-cert' kind='KongCACertificate' %} + +At this point, you should see the CA Certificate in the Gateway Manager UI. diff --git a/app/_src/gateway-operator/guides/konnect-entities/consumer-and-consumergroup.md b/app/_src/gateway-operator/guides/konnect-entities/consumer-and-consumergroup.md new file mode 100644 index 000000000000..825eba79bda2 --- /dev/null +++ b/app/_src/gateway-operator/guides/konnect-entities/consumer-and-consumergroup.md @@ -0,0 +1,138 @@ +--- +title: Consumer, Credentials and Consumer Group +--- + +In this guide you'll learn how to use the `KongConsumer` and `KongConsumerGroup` custom resources to +manage {{site.konnect_product_name}} [Consumers](/konnect/gateway-manager/configuration/#consumers) +and consumer groups natively from your Kubernetes cluster. + +{% include md/kgo/konnect-entities-prerequisites.md disable_accordian=false version=page.version release=page.release +with-control-plane=true %} + +## Create a consumer + +Creating the `KongConsumer` object in your Kubernetes cluster will provision a {{site.konnect_product_name}} Consumer in +your [Gateway Manager](/konnect/gateway-manager). +You can refer to the CR [API](/gateway-operator/{{ page.release }}/reference/custom-resources/#kongconsumer) +to see all the available fields. + +Your `KongConsumer` must be associated with a `KonnectGatewayControlPlane` object that you've created in your cluster. +It will make it part of the Gateway Control Plane's configuration. + +You can create a `KongConsumer` by applying the following YAML manifest: + +```yaml +echo ' +kind: KongConsumer +apiVersion: configuration.konghq.com/v1 +metadata: + name: consumer + namespace: default +username: consumer +custom_id: 08433C12-2B81-4738-B61D-3AA2136F0212 # Optional +spec: + controlPlaneRef: + type: konnectNamespacedRef + konnectNamespacedRef: + name: gateway-control-plane # Reference to the KonnectGatewayControlPlane object + ' | kubectl apply -f - +``` + +{% include md/kgo/check-condition.md name='consumer' kind='KongConsumer' %} + +At this point, you should see the consumer in the Gateway Manager UI. + +## Associate the consumer with credentials + +Consumers can have credentials associated with them. You can create one of the supported credential types. Please refer +to the below custom resource's documentation links to learn all the available fields for each credential type. + +- [KongCredentialBasicAuth](/gateway-operator/{{ page.release }}/reference/custom-resources/#kongcredentialbasicauth) +- [KongCredentialKeyAuth](/gateway-operator/{{ page.release }}/reference/custom-resources/#kongcredentialkeyauth) +- [KongCredentialACL](/gateway-operator/{{ page.release }}/reference/custom-resources/#kongcredentialacl) +- [KongCredentialJWT](/gateway-operator/{{ page.release }}/reference/custom-resources/#kongcredentialjwt) +- [KongCredentialHMAC](/gateway-operator/{{ page.release }}/reference/custom-resources/#kongcredentialhmac) + +For example, you can create a `KongCredentialBasicAuth` associated with the `consumer` `KongConsumer` by applying the +following YAML manifest: + +```yaml +echo ' +apiVersion: configuration.konghq.com/v1alpha1 +kind: KongCredentialBasicAuth +metadata: + name: basic-auth-cred + namespace: default +spec: + consumerRef: + name: consumer # Reference to the KongConsumer object + password: pass + username: username + ' | kubectl apply -f - +``` + +{% include md/kgo/check-condition.md name='basic-auth-cred' kind='KongCredentialBasicAuth' %} + +At this point, you should see the credential in the consumer's credentials in the Gateway Manager UI. + +## Create a consumer group + +Creating the `KongConsumerGroup` object in your Kubernetes cluster will provision a {{site.konnect_product_name}} consumer group in +your [Gateway Manager](/konnect/gateway-manager). Please refer to the +`KongConsumerGroup` CR [API](/gateway-operator/{{ page.release }}/reference/custom-resources/#kongconsumergroup) to see +all the available fields. + +You can create a `KongConsumerGroup` by applying the following YAML manifest: + +```yaml +echo ' +kind: KongConsumerGroup +apiVersion: configuration.konghq.com/v1beta1 +metadata: + name: consumer-group + namespace: default +spec: + name: consumer-group + controlPlaneRef: + type: konnectNamespacedRef + konnectNamespacedRef: + name: gateway-control-plane # Reference to the KonnectGatewayControlPlane object +' | kubectl apply -f - +``` + +{% include md/kgo/check-condition.md name='consumer-group' kind='KongConsumerGroup' %} + +At this point, you should see the consumer group in the Gateway Manager UI. + +### Associate a consumer with a consumer group + +You can associate a `KongConsumer` with a `KongConsumerGroup` by modifying the `KongConsumer` object and adding the +`consumerGroups` field. This field is a list of `KongConsumerGroup` names. + +For example, you can associate the `consumer` `KongConsumer` with the `consumer-group` `KongConsumerGroup` by applying the +following YAML manifest: + +```yaml +echo ' +kind: KongConsumer +apiVersion: configuration.konghq.com/v1 +metadata: + name: consumer + namespace: default +username: consumer +custom_id: 08433C12-2B81-4738-B61D-3AA2136F0212 # Optional +consumerGroups: + - consumer-group # Reference to the KongConsumerGroup object +spec: + controlPlaneRef: + type: konnectNamespacedRef + konnectNamespacedRef: + name: gateway-control-plane # Reference to the KonnectGatewayControlPlane object + ' | kubectl apply -f - +``` + +You can verify the `KongConsumer`'s `consumerGroups` field was reconciled successfully by checking its `KongConsumerGroupRefsValid` condition. + +{% include md/kgo/check-condition.md name='consumer' kind='KongConsumer' conditionType='KongConsumerGroupRefsValid' reason='Valid' disableDescription=true %} + +At this point, you should see the `consumer` Consumer in the Consumer Group members in the Gateway Manager UI. diff --git a/app/_src/gateway-operator/guides/konnect-entities/dpcertificate.md b/app/_src/gateway-operator/guides/konnect-entities/dpcertificate.md new file mode 100644 index 000000000000..5a9c6f943525 --- /dev/null +++ b/app/_src/gateway-operator/guides/konnect-entities/dpcertificate.md @@ -0,0 +1,54 @@ +--- +title: Data Plane Client Certificate +--- + +In this guide you'll learn how to use the `KongDataPlaneClientCertificate` custom resource to manage +Konnect [Vault](/konnect/gateway-manager/configuration/#vaults) natively from your Kubernetes cluster. + +{% include md/kgo/konnect-entities-prerequisites.md disable_accordian=false version=page.version release=page.release +with-control-plane=true %} + +## Create a data plane client certificate + +Creating the `KongDataPlaneClientCertificate` object in your Kubernetes cluster will provision a data plane client certificate in +your [Gateway Manager](/konnect/gateway-manager). You can refer to the CR [API](/gateway-operator/{{ page.release +}}/reference/custom-resources/#kongdataplaneclientcertificate) to see all the available fields. + +Your `KongDataPlaneClientCertificate` must be associated with a `KonnectGatewayControlPlane` object that you've created in your cluster. +It will make it part of the gateway control plane's configuration. + +To create a `KongDataPlaneClientCertificate`, you can apply the following YAML manifest: + +```yaml +echo ' +kind: KongDataPlaneClientCertificate +apiVersion: configuration.konghq.com/v1alpha1 +metadata: + name: dp-cert + namespace: default +spec: + controlPlaneRef: + type: konnectNamespacedRef # This indicates that an in cluster reference is used + konnectNamespacedRef: + name: gateway-control-plane # Reference to the KonnectGatewayControlPlane object + cert: | # Sample certificate in PEM format, replace with your own + -----BEGIN CERTIFICATE----- + MIIB4TCCAYugAwIBAgIUAenxUyPjkSLCe2BQXoBMBacqgLowDQYJKoZIhvcNAQEL + BQAwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM + GEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDAeFw0yNDEwMjgyMDA3NDlaFw0zNDEw + MjYyMDA3NDlaMEUxCzAJBgNVBAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEw + HwYDVQQKDBhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQwXDANBgkqhkiG9w0BAQEF + AANLADBIAkEAyzipjrbAaLO/yPg7lL1dLWzhqNdc3S4YNR7f1RG9whWhbsPE2z42 + e6WGFf9hggP6xjG4qbU8jFVczpd1UPwGbQIDAQABo1MwUTAdBgNVHQ4EFgQUkPPB + ghj+iHOHAKJlC1gLbKT/ZHQwHwYDVR0jBBgwFoAUkPPBghj+iHOHAKJlC1gLbKT/ + ZHQwDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAANBALfy49GvA2ld+u+G + Koxa8kCt7uywoqu0hfbBfUT4HqmXPvsuhz8RinE5ltxId108vtDNlD/+bKl+N5Ub + qKjBs0k= + -----END CERTIFICATE----- + ' | kubectl apply -f - +``` + + +{% include md/kgo/check-condition.md name='dp-cert' kind='KongDataPlaneClientCertificate' %} + +At this point, you should see the Data Plane Client Certificate in the Gateway Manager UI. 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..3fb0b1a94abf --- /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 %} + +## Create a self-managed hybrid gateway control plane + +Creating the `KonnectGatewayControlPlane` object in your Kubernetes cluster will provision a {{site.konnect_short_name}} 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 +``` + +## Create 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 +``` + +### Add 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. + +## Create 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 +``` diff --git a/app/_src/gateway-operator/guides/konnect-entities/key-and-keyset.md b/app/_src/gateway-operator/guides/konnect-entities/key-and-keyset.md new file mode 100644 index 000000000000..e0f28aa5d55a --- /dev/null +++ b/app/_src/gateway-operator/guides/konnect-entities/key-and-keyset.md @@ -0,0 +1,158 @@ +--- +title: Key and Key Set +--- + +In this guide you'll learn how to use the `KongKey` and `KongKeySet` custom resources to +manage {{site.konnect_product_name}} [keys](/konnect/gateway-manager/configuration/#keys) +and key sets natively from your Kubernetes cluster. + +{% include md/kgo/konnect-entities-prerequisites.md disable_accordian=false version=page.version release=page.release +with-control-plane=true %} + +## Create a Key + +Creating the `KongKey` object in your Kubernetes cluster will provision a {{site.konnect_product_name}} key in +your [Gateway Manager](/konnect/gateway-manager). +You can refer to the CR [API](/gateway-operator/{{ page.release }}/reference/custom-resources/#kongkey) +to see all the available fields. + +Your `KongKey` must be associated with a `KonnectGatewayControlPlane` object that you've created in your cluster. +It will make it part of the Gateway control plane's configuration. + +`KongKey` supports two types of keys: JWK and PEM. You can create a PEM `KongKey` by providing `spec.pem.private_key` +and `spec.pem.public_key` fields. For JWK keys, you should provide `spec.jwk` field with the JWK key string +representation. + +For this example, we will create a PEM `KongKey` by applying the following YAML manifest: + +```yaml +echo ' +kind: KongKey +apiVersion: configuration.konghq.com/v1alpha1 +metadata: + name: key + namespace: default +spec: + controlPlaneRef: + type: konnectNamespacedRef # This indicates that an in cluster reference is used + konnectNamespacedRef: + name: gateway-control-plane # Reference to the KonnectGatewayControlPlane object + kid: key-id + name: key + pem: + private_key: | # Sample private key in PEM format, replace with your own + -----BEGIN PRIVATE KEY----- + MIIBVQIBADANBgkqhkiG9w0BAQEFAASCAT8wggE7AgEAAkEA4f5Ur6EzZKsfu0ct + QCmmbCkUohHp6lAgGGmVmQpj5Xrx5jrjGWWdDAF1ADFPh/XMC58iZFaX33UpGOUn + tuWbJQIDAQABAkEAxqXvvL2+1iNRbiY/kWHLBtIJb/i9G5i4zZypwe+PJduIPRlH + 4bFHih8sHtYt5rEs4RnT0SJnZN1HKhJcisVLdQIhAPKboGS0dTprmMLrAXQh15p7 + xz4XUbZrNqPct+hqa5JXAiEA7nfrjPYm2UXKRzvFo9Zbd9K/Y3M0Xas9LsXdRaO8 + 6OMCIAhkX8D8CQ4TSL59WJiGzyl13KeGMPppbQNwECCHBd+TAiB8dDOHprORsz2l + PYmhPu8PsvpVkbtjo0nUDkmz3Ydq1wIhAIMCsZQ7A3H/kN88aYsqKeGg9c++yqIP + /9xIOKHsjlB4 + -----END PRIVATE KEY----- + public_key: | # Sample public key in PEM format, replace with your own + -----BEGIN PUBLIC KEY----- + MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOH+VK+hM2SrH7tHLUAppmwpFKIR6epQ + IBhplZkKY+V68eY64xllnQwBdQAxT4f1zAufImRWl991KRjlJ7blmyUCAwEAAQ== + -----END PUBLIC KEY----- + ' | kubectl apply -f - +``` + +{% include md/kgo/check-condition.md name='key' kind='KongKey' %} + +At this point, you should see the key in the Gateway Manager UI. + +## Create a key set + +Creating the `KongKeySet` object in your Kubernetes cluster will provision a {{site.konnect_product_name}} key set in +your [Gateway Manager](/konnect/gateway-manager). You can refer to the CR [API](/gateway-operator/{{ page.release +}}/reference/custom-resources/#kongkeyset) +to see all the available fields. + +Your `KongKeySet` must be associated with a `KonnectGatewayControlPlane` object that you've created in your cluster. + +To create a `KongKeySet`, you can apply the following YAML manifest: + +```yaml +echo ' +kind: KongKeySet +apiVersion: configuration.konghq.com/v1alpha1 +metadata: + name: key-set + namespace: default +spec: + controlPlaneRef: + type: konnectNamespacedRef # This indicates that an in cluster reference is used + konnectNamespacedRef: + name: gateway-control-plane # KonnectGatewayControlPlane reference + name: key-set + ' | kubectl apply -f - +``` + +{% include md/kgo/check-condition.md name='key-set' kind='KongKeySet' %} + +At this point, you should see the key set in the Gateway Manager UI. + +### Associate the key with the key set + +A single `KongKey` can be associated with only one `KongKeySet`. To associate a `KongKey` with a `KongKeySet`, you need +to update the `KongKey` object with the `keySetRef` field. You can do this by applying the following YAML manifest: + +```yaml +echo ' +kind: KongKey +apiVersion: configuration.konghq.com/v1alpha1 +metadata: + name: key + namespace: default +spec: + controlPlaneRef: + type: konnectNamespacedRef # This indicates that an in cluster reference is used + konnectNamespacedRef: + name: gateway-control-plane # KonnectGatewayControlPlane reference + kid: key-id + name: key + pem: + private_key: | # Sample private key in PEM format, replace with your own + -----BEGIN PRIVATE KEY----- + MIIBVQIBADANBgkqhkiG9w0BAQEFAASCAT8wggE7AgEAAkEA4f5Ur6EzZKsfu0ct + QCmmbCkUohHp6lAgGGmVmQpj5Xrx5jrjGWWdDAF1ADFPh/XMC58iZFaX33UpGOUn + tuWbJQIDAQABAkEAxqXvvL2+1iNRbiY/kWHLBtIJb/i9G5i4zZypwe+PJduIPRlH + 4bFHih8sHtYt5rEs4RnT0SJnZN1HKhJcisVLdQIhAPKboGS0dTprmMLrAXQh15p7 + xz4XUbZrNqPct+hqa5JXAiEA7nfrjPYm2UXKRzvFo9Zbd9K/Y3M0Xas9LsXdRaO8 + 6OMCIAhkX8D8CQ4TSL59WJiGzyl13KeGMPppbQNwECCHBd+TAiB8dDOHprORsz2l + PYmhPu8PsvpVkbtjo0nUDkmz3Ydq1wIhAIMCsZQ7A3H/kN88aYsqKeGg9c++yqIP + /9xIOKHsjlB4 + -----END PRIVATE KEY----- + public_key: | # Sample public key in PEM format, replace with your own + -----BEGIN PUBLIC KEY----- + MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOH+VK+hM2SrH7tHLUAppmwpFKIR6epQ + IBhplZkKY+V68eY64xllnQwBdQAxT4f1zAufImRWl991KRjlJ7blmyUCAwEAAQ== + -----END PUBLIC KEY----- + keySetRef: + type: namespacedRef + namespacedRef: + name: key-set # KongKeySet reference + ' | kubectl apply -f - +``` + +You can verify the `KongKey` was successfully associated with the `KongKeySet` by checking its `KeySetRefValid` +condition. + +```shell +kubectl get kongkey key -o=jsonpath='{.status.conditions}' | jq '.[] | select(.type == "KeySetRefValid")' +``` + +The output should look similar to this: + +```console +{ + "observedGeneration": 2, + "reason": "Valid", + "status": "True", + "type": "KeySetRefValid" +} +``` + +At this point, you should see the key associated with the key set in the Gateway Manager UI. diff --git a/app/_src/gateway-operator/guides/konnect-entities/service-and-route.md b/app/_src/gateway-operator/guides/konnect-entities/service-and-route.md new file mode 100644 index 000000000000..a1477b47bf1f --- /dev/null +++ b/app/_src/gateway-operator/guides/konnect-entities/service-and-route.md @@ -0,0 +1,110 @@ +--- +title: Service and Route +--- + +In this guide you'll learn how to use the `KongService` and `KongRoute` custom resources to +manage {{site.konnect_product_name}} [services](/konnect/gateway-manager/configuration/#gateway-services) +and [routes](/konnect/gateway-manager/configuration/#routes) natively from your Kubernetes cluster. + +{% include md/kgo/konnect-entities-prerequisites.md disable_accordian=false version=page.version release=page.release +with-control-plane=true %} + +## Create a service + +Creating the `KongService` object in your Kubernetes cluster will provision a {{site.konnect_product_name}} service in +your [Gateway Manager](/konnect/gateway-manager). +You can refer to the CR [API](/gateway-operator/{{ page.release }}/reference/custom-resources/#kongservice) +to see all the available fields. + +Your `KongService` must be associated with a `KonnectGatewayControlPlane` object that you've created in your cluster. +It will make it part of the Gateway control plane's configuration. + +You can create a `KongService` by applying the following YAML manifest: + +```yaml +echo ' +kind: KongService +apiVersion: configuration.konghq.com/v1alpha1 +metadata: + name: service + namespace: default +spec: + name: service + host: example.com + controlPlaneRef: + type: konnectNamespacedRef # This indicates that an in cluster reference is used + konnectNamespacedRef: + name: gateway-control-plane # Reference to the KonnectGatewayControlPlane object + ' | kubectl apply -f - +``` + +{% include md/kgo/check-condition.md name='service' kind='KongService' %} + +At this point, you should see the Service in the Gateway Manager UI. + +## Create a route + +Creating the `KongRoute` object in your Kubernetes cluster will provision a {{site.konnect_product_name}} route in +your [Gateway Manager](/konnect/gateway-manager). +You can refer to the CR [API](/gateway-operator/{{ page.release }}/reference/custom-resources/#kongroute) to see all the available fields. + +Your `KongRoute` can either be associated with a `KongService` (and inherit the relation with a `KonnectGatewayControlPlane` from it) +or be directly associated with a `KonnectGatewayControlPlane` object when referring a `KongService`. + +### Associate a route with a service + +You can create a `KongRoute` associated with a `KongService` by applying the following YAML manifest: + +```yaml +echo ' +kind: KongRoute +apiVersion: configuration.konghq.com/v1alpha1 +metadata: + name: route-with-service + namespace: default +spec: + name: route-with-service + protocols: + - http + hosts: + - example.com + serviceRef: + type: namespacedRef + namespacedRef: + name: service # KongService reference +' | kubectl apply -f - +``` + +{% include md/kgo/check-condition.md name='route-with-service' kind='KongRoute' %} + +At this point, you should see the Route in the Gateway Manager UI. + +### Associate a route with a gateway control plane + +You can also create a `KongRoute` that won't refer any `KongService`. In that case, you must associate it with a +`KonnectGatewayControlPlane` so that {{site.kgo_product_name}} knows what Gateway control plane it should be created in. +You can do so by applying the following YAML manifest: + +```yaml +echo ' +kind: KongRoute +apiVersion: configuration.konghq.com/v1alpha1 +metadata: + name: route-without-service + namespace: default +spec: + name: route-without-service + protocols: + - http + hosts: + - example.com + controlPlaneRef: + type: konnectNamespacedRef + konnectNamespacedRef: + name: gateway-control-plane # Reference to the KonnectGatewayControlPlane object +' | kubectl apply -f - +``` + +{% include md/kgo/check-condition.md name='route-without-service' kind='KongRoute' %} + +At this point, you should see the route in the Gateway Manager UI. diff --git a/app/_src/gateway-operator/guides/konnect-entities/tagging-and-labeling.md b/app/_src/gateway-operator/guides/konnect-entities/tagging-and-labeling.md new file mode 100644 index 000000000000..8c7152ec304c --- /dev/null +++ b/app/_src/gateway-operator/guides/konnect-entities/tagging-and-labeling.md @@ -0,0 +1,80 @@ +--- +title: Tagging and Labeling +--- + +Tags and labels are a way to organize and categorize your resources. In this guide, you'll learn how to annotate your +Konnect entities managed by {{site.kgo_product_name}} with tags and labels (depending on particular entity's support for +those). + +{% include md/kgo/konnect-entities-prerequisites.md disable_accordian=false version=page.version release=page.release %} + +## Labeling + +Labels are key-value pairs that you can attach to objects. As of now, the only Konnect entity that supports labeling is +the [KonnectGatewayControlPlane](/gateway-operator/guides/konnect-entities/gatewaycontrolplane). You can add labels to +the `KonnectGatewayControlPlane` object by specifying the `labels` field in the `spec` section. + +```yaml +echo ' +kind: KonnectGatewayControlPlane +apiVersion: konnect.konghq.com/v1alpha1 +metadata: + name: gateway-control-plane + namespace: default +spec: + labels: # Arbitrary key-value pairs + environment: production + team: devops + name: gateway-control-plane + konnect: + authRef: + name: konnect-api-auth # Reference to the KonnectAPIAuthConfiguration object + ' | kubectl apply -f - +``` + +You can verify the control plane was reconciled successfully by checking its status. + +```shell +kubectl get konnectgatewaycontrolplanes.konnect.konghq.com gateway-control-plane +``` + +The output should look similar to this: + +```console +NAME PROGRAMMED ID ORGID +gateway-control-plane True +``` + +At this point, labels should be visible in the Gateway Manager UI. + +## Tagging + +Tags are values that you can attach to objects. All the {{site.konnect_product_name}} entities that can be attached to a +`KonnectGatewayControlPlane` object support tagging. You can add tags to those entities by specifying the `tags` field +in their `spec` section. + +For example, to add tags to a `KongService` object, you can apply the following YAML manifest: + +```yaml +echo ' +kind: KongService +apiVersion: configuration.konghq.com/v1alpha1 +metadata: + name: service + namespace: default +spec: + tags: # Arbitrary list of strings + - production + - devops + name: service + host: example.com + controlPlaneRef: + type: konnectNamespacedRef + konnectNamespacedRef: + name: gateway-control-plane # Reference to the KonnectGatewayControlPlane object + ' | kubectl apply -f - +``` + +{% include md/kgo/check-condition.md name='service' kind='KongService' %} + +At this point, tags should be visible in the Gateway Manager UI. diff --git a/app/_src/gateway-operator/guides/konnect-entities/upstream-and-target.md b/app/_src/gateway-operator/guides/konnect-entities/upstream-and-target.md new file mode 100644 index 000000000000..b1cb3a9ba375 --- /dev/null +++ b/app/_src/gateway-operator/guides/konnect-entities/upstream-and-target.md @@ -0,0 +1,93 @@ +--- +title: Upstream and Target +--- + +In this guide you'll learn how to use the `KongUpstream` and `KongTarget` custom resources to +manage {{site.konnect_product_name}} [upstreams](/konnect/gateway-manager/configuration/#upstreams) +and their targets natively from your Kubernetes cluster. + +{% include md/kgo/konnect-entities-prerequisites.md disable_accordian=false version=page.version release=page.release +with-control-plane=true %} + +## Create an upstream + +Creating the `KongUpstream` object in your Kubernetes cluster will provision a {{site.konnect_product_name}} key in +your [Gateway Manager](/konnect/gateway-manager). +You can refer to the CR [API](/gateway-operator/{{ page.release }}/reference/custom-resources/#kongupstream) +to see all the available fields. + +Your `KongUpstream` must be associated with a `KonnectGatewayControlPlane` object that you've created in your cluster. +It will make it part of the Gateway Control Plane's configuration. + +To create a `KongUpstream`, you can apply the following YAML manifest: + +```yaml +echo ' +kind: KongUpstream +apiVersion: configuration.konghq.com/v1alpha1 +metadata: + name: upstream + namespace: default +spec: + name: upstream + controlPlaneRef: + type: konnectNamespacedRef # This indicates that an in cluster reference is used + konnectNamespacedRef: + name: gateway-control-plane # KonnectGatewayControlPlane reference + ' | kubectl apply -f - +``` + +{% include md/kgo/check-condition.md name='upstream' kind='KongUpstream' %} + +At this point, you should see the Upstream in the Gateway Manager UI. + +## Create a target + +Each `KongTarget` must be associated with a `KongUpstream` it's meant to be a backend for. For this reason, you must +specify the `upstreamRef` field in the `spec` section of the `KongTarget` object. Please refer to the CR [API]( +/gateway-operator/{{ page.release }}/reference/custom-resources/#kongtarget) +to see all the available fields. + +To create two different `KongTarget`s associated with the `KongUpstream` created before, you can apply the following +YAML manifest: + +```yaml +echo ' +kind: KongTarget +apiVersion: configuration.konghq.com/v1alpha1 +metadata: + name: target-a + namespace: default +spec: + upstreamRef: + name: upstream # Reference to the KongUpstream object + target: "10.0.0.1" + weight: 30 +--- +kind: KongTarget +apiVersion: configuration.konghq.com/v1alpha1 +metadata: + name: target-b + namespace: default +spec: + upstreamRef: + name: upstream # Reference to the KongUpstream object + target: "10.0.0.2" + weight: 70 + ' | kubectl apply -f - +``` + +You can verify both `KongTarget`s successfully were associated with the `KongUpstream` by checking their +`KongUpstreamRefValid` condition. + +{% include md/kgo/check-condition.md name='target-a' kind='KongTarget' conditionType='KongUpstreamRefValid' reason='Valid' disableDescription=true %} + +{% include md/kgo/check-condition.md name='target-b' kind='KongTarget' conditionType='KongUpstreamRefValid' reason='Valid' disableDescription=true %} + +You can also verify both `KongTarget`s were reconciled successfully by checking their `Programmed` condition. + +{% include md/kgo/check-condition.md name='target-a' kind='KongTarget' disableDescription=true %} + +{% include md/kgo/check-condition.md name='target-b' kind='KongTarget' disableDescription=true %} + +At this point, you should see both Targets in the `upstream` Upstream in the Gateway Manager UI. diff --git a/app/_src/gateway-operator/guides/konnect-entities/vault.md b/app/_src/gateway-operator/guides/konnect-entities/vault.md new file mode 100644 index 000000000000..95702cb1e723 --- /dev/null +++ b/app/_src/gateway-operator/guides/konnect-entities/vault.md @@ -0,0 +1,58 @@ +--- +title: Vault +--- + +In this guide you'll learn how to use the `KongVault` custom resource to manage +{{site.konnect_product_name}} [Vault](/konnect/gateway-manager/configuration/#vaults) natively from your Kubernetes cluster. + +{% include md/kgo/konnect-entities-prerequisites.md disable_accordian=false version=page.version release=page.release +with-control-plane=true %} + +## Create a vault + +Creating the `KongVault` object in your Kubernetes cluster will provision a {{site.konnect_product_name}} Vault in +your [Gateway Manager](/konnect/gateway-manager). You can refer to the CR [API](/gateway-operator/{{ page.release +}}/reference/custom-resources/#kongvault) to see all the available fields. + +Your `KongVault` must be associated with a `KonnectGatewayControlPlane` object that you've created in your cluster. +It will make it part of the Gateway control plane's configuration. + +To create a `KongVault`, you can apply the following YAML manifest: + +```yaml +echo ' +kind: KongVault +apiVersion: configuration.konghq.com/v1alpha1 +metadata: + name: env-vault +spec: + backend: env + prefix: env-vault + config: + prefix: env-vault + controlPlaneRef: + type: konnectNamespacedRef # This indicates that an in cluster reference is used + konnectNamespacedRef: + name: gateway-control-plane # Reference to the KonnectGatewayControlPlane object + namespace: default # KongVault is cluster scoped, so we need to specify namespace of the Konnect Control Plane + ' | kubectl apply -f - +``` + +You can verify the `KongVault` was reconciled successfully by checking its `Programmed` condition. + +```shell +kubectl get kongvault env-vault -o=jsonpath='{.status.conditions}' | jq '.[] | select(.type == "Programmed")' +``` + +The output should look similar to this: + +```console +{ + "observedGeneration": 1, + "reason": "Programmed", + "status": "True", + "type": "Programmed" +} +``` + +At this point, you should see the Vault in the Gateway Manager UI.