From 14be1f120727ebeb713dcebb3a2933ad494f6cb2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Grzegorz=20Burzy=C5=84ski?= Date: Fri, 25 Oct 2024 17:36:15 +0200 Subject: [PATCH] docs(kgo): add Key and KeySet Konnect entities guide --- app/_data/docs_nav_kgo_1.4.x.yml | 4 +- .../guides/konnect-entities/key-and-keyset.md | 188 ++++++++++++++++++ 2 files changed, 191 insertions(+), 1 deletion(-) create mode 100644 app/_src/gateway-operator/guides/konnect-entities/key-and-keyset.md diff --git a/app/_data/docs_nav_kgo_1.4.x.yml b/app/_data/docs_nav_kgo_1.4.x.yml index 7558692bba18..e56b8da1d473 100644 --- a/app/_data/docs_nav_kgo_1.4.x.yml +++ b/app/_data/docs_nav_kgo_1.4.x.yml @@ -103,7 +103,7 @@ items: url: /guides/upgrade/data-plane/rolling/ - text: Blue / Green Deployment url: /guides/upgrade/data-plane/blue-green/ - - text: Konnect entities + - text: Managing Konnect entities items: - text: Gateway Control Plane url: /guides/konnect-entities/gatewaycontrolplane/ @@ -111,6 +111,8 @@ items: 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/ - title: Reference icon: /assets/images/icons/icn-magnifying-glass.svg items: 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..07ba2ac85fac --- /dev/null +++ b/app/_src/gateway-operator/guides/konnect-entities/key-and-keyset.md @@ -0,0 +1,188 @@ +--- +title: Key and Key Set +--- + +In this guide you'll learn how to use the `KongKey` and `KongKeySet` custom resources to +manage Konnect [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 Konnect 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 + 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----- + ' | kubectl apply -f - +``` + +You can verify the `KongKey` was reconciled successfully by checking its `Programmed` condition. + +```shell +kubectl get kongkey key -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 Key in the Gateway Manager UI. + +## Create a Key Set + +Creating the `KongKeySet` object in your Kubernetes cluster will provision a Konnect 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 + konnectNamespacedRef: + name: gateway-control-plane # KonnectGatewayControlPlane reference + name: key-set + ' | kubectl apply -f - +``` + +You can verify the `KongKeySet` was reconciled successfully by checking its `Programmed` condition. + +```shell +kubectl get kongkeyset key-set -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 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 + 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.