Certificates entity page (#182)

* First draft of Certificates entity page Signed-off-by: Diana <[email protected]> * Add better key and cert examples, add missing cert UI instructions Signed-off-by: Diana <[email protected]> * Fix example cert and key formatting Signed-off-by: Diana <[email protected]> * Remove related resources and fix entity type * Rename certificate entity file and card Signed-off-by: Diana <[email protected]> * Add schema to frontmatter Signed-off-by: Diana <[email protected]> * Add missing id to examples Signed-off-by: Diana <[email protected]> * Add placeholder SSL certificate how to Signed-off-by: Diana <[email protected]> * Add how to answer for tldr * Add stub pages for CA certs entity and TLS passthrough Signed-off-by: Diana <[email protected]> * add config * remove sources.yml --------- Signed-off-by: Diana <[email protected]> Co-authored-by: Angel <[email protected]>
Kong · Jan 10, 2025 · 727d2fa · 727d2fa
1 parent 1e4dc0c
commit 727d2fa
Show file tree

Hide file tree

Showing 8 changed files with 278 additions and 0 deletions.
diff --git a/app/_data/entity_examples/certificates/example-certificate.yml b/app/_data/entity_examples/certificates/example-certificate.yml
@@ -0,0 +1,53 @@
+cert: |
+  -----BEGIN CERTIFICATE-----
+  MIID0DCCArigAwIBAgIBATANBgkqhkiG9w0BAQUFADB/MQswCQYDVQQGEwJGUjET
+  MBEGA1UECAwKU29tZS1TdGF0ZTEOMAwGA1UEBwwFUGFyaXMxDTALBgNVBAoMBERp
+  bWkxDTALBgNVBAsMBE5TQlUxEDAOBgNVBAMMB0RpbWkgQ0ExGzAZBgkqhkiG9w0B
+  CQEWDGRpbWlAZGltaS5mcjAeFw0xNDAxMjgyMDM2NTVaFw0yNDAxMjYyMDM2NTVa
+  MFsxCzAJBgNVBAYTAkZSMRMwEQYDVQQIDApTb21lLVN0YXRlMSEwHwYDVQQKDBhJ
+  bnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQxFDASBgNVBAMMC3d3dy5kaW1pLmZyMIIB
+  IjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvpnaPKLIKdvx98KW68lz8pGa
+  RRcYersNGqPjpifMVjjE8LuCoXgPU0HePnNTUjpShBnynKCvrtWhN+haKbSp+QWX
+  SxiTrW99HBfAl1MDQyWcukoEb9Cw6INctVUN4iRvkn9T8E6q174RbcnwA/7yTc7p
+  1NCvw+6B/aAN9l1G2pQXgRdYC/+G6o1IZEHtWhqzE97nY5QKNuUVD0V09dc5CDYB
+  aKjqetwwv6DFk/GRdOSEd/6bW+20z0qSHpa3YNW6qSp+x5pyYmDrzRIR03os6Dau
+  ZkChSRyc/Whvurx6o85D6qpzywo8xwNaLZHxTQPgcIA5su9ZIytv9LH2E+lSwwID
+  AQABo3sweTAJBgNVHRMEAjAAMCwGCWCGSAGG+EIBDQQfFh1PcGVuU1NMIEdlbmVy
+  YXRlZCBDZXJ0aWZpY2F0ZTAdBgNVHQ4EFgQU+tugFtyN+cXe1wxUqeA7X+yS3bgw
+  HwYDVR0jBBgwFoAUhMwqkbBrGp87HxfvwgPnlGgVR64wDQYJKoZIhvcNAQEFBQAD
+  ggEBAIEEmqqhEzeXZ4CKhE5UM9vCKzkj5Iv9TFs/a9CcQuepzplt7YVmevBFNOc0
+  +1ZyR4tXgi4+5MHGzhYCIVvHo4hKqYm+J+o5mwQInf1qoAHuO7CLD3WNa1sKcVUV
+  vepIxc/1aHZrG+dPeEHt0MdFfOw13YdUc2FH6AqEdcEL4aV5PXq2eYR8hR4zKbc1
+  fBtuqUsvA8NWSIyzQ16fyGve+ANf6vXvUizyvwDrPRv/kfvLNa3ZPnLMMxU98Mvh
+  PXy3PkB8++6U4Y3vdk2Ni2WYYlIls8yqbM4327IKmkDc2TimS8u60CT47mKU7aDY
+  cbTV5RDkrlaYwm5yqlTIglvCv7o=
+  -----END CERTIFICATE-----
+id: b2f34145-0343-41a4-9602-4c69dec2f269
+key: |
+  -----BEGIN RSA PRIVATE KEY-----
+  MIIEowIBAAKCAQEAvpnaPKLIKdvx98KW68lz8pGaRRcYersNGqPjpifMVjjE8LuC
+  oXgPU0HePnNTUjpShBnynKCvrtWhN+haKbSp+QWXSxiTrW99HBfAl1MDQyWcukoE
+  b9Cw6INctVUN4iRvkn9T8E6q174RbcnwA/7yTc7p1NCvw+6B/aAN9l1G2pQXgRdY
+  C/+G6o1IZEHtWhqzE97nY5QKNuUVD0V09dc5CDYBaKjqetwwv6DFk/GRdOSEd/6b
+  W+20z0qSHpa3YNW6qSp+x5pyYmDrzRIR03os6DauZkChSRyc/Whvurx6o85D6qpz
+  ywo8xwNaLZHxTQPgcIA5su9ZIytv9LH2E+lSwwIDAQABAoIBAFml8cD9a5pMqlW3
+  f9btTQz1sRL4Fvp7CmHSXhvjsjeHwhHckEe0ObkWTRsgkTsm1XLu5W8IITnhn0+1
+  iNr+78eB+rRGngdAXh8diOdkEy+8/Cee8tFI3jyutKdRlxMbwiKsouVviumoq3fx
+  OGQYwQ0Z2l/PvCwy/Y82ffq3ysC5gAJsbBYsCrg14bQo44ulrELe4SDWs5HCjKYb
+  EI2b8cOMucqZSOtxg9niLN/je2bo/I2HGSawibgcOdBms8k6TvsSrZMr3kJ5O6J+
+  77LGwKH37brVgbVYvbq6nWPL0xLG7dUv+7LWEo5qQaPy6aXb/zbckqLqu6/EjOVe
+  ydG5JQECgYEA9kKfTZD/WEVAreA0dzfeJRu8vlnwoagL7cJaoDxqXos4mcr5mPDT
+  kbWgFkLFFH/AyUnPBlK6BcJp1XK67B13ETUa3i9Q5t1WuZEobiKKBLFm9DDQJt43
+  uKZWJxBKFGSvFrYPtGZst719mZVcPct2CzPjEgN3Hlpt6fyw3eOrnoECgYEAxiOu
+  jwXCOmuGaB7+OW2tR0PGEzbvVlEGdkAJ6TC/HoKM1A8r2u4hLTEJJCrLLTfw++4I
+  ddHE2dLeR4Q7O58SfLphwgPmLDezN7WRLGr7Vyfuv7VmaHjGuC3Gv9agnhWDlA2Q
+  gBG9/R9oVfL0Dc7CgJgLeUtItCYC31bGT3yhV0MCgYEA4k3DG4L+RN4PXDpHvK9I
+  pA1jXAJHEifeHnaW1d3vWkbSkvJmgVf+9U5VeV+OwRHN1qzPZV4suRI6M/8lK8rA
+  Gr4UnM4aqK4K/qkY4G05LKrik9Ev2CgqSLQDRA7CJQ+Jn3Nb50qg6hFnFPafN+J7		
+  7juWln08wFYV4Atpdd+9XQECgYBxizkZFL+9IqkfOcONvWAzGo+Dq1N0L3J4iTIk
+  w56CKWXyj88d4qB4eUU3yJ4uB4S9miaW/eLEwKZIbWpUPFAn0db7i6h3ZmP5ZL8Q
+  qS3nQCb9DULmU2/tU641eRUKAmIoka1g9sndKAZuWo+o6fdkIb1RgObk9XNn8R4r
+  psv+aQKBgB+CIcExR30vycv5bnZN9EFlIXNKaeMJUrYCXcRQNvrnUIUBvAO8+jAe
+  CdLygS5RtgOLZib0IVErqWsP3EI1ACGuLts0vQ9GFLQGaN1SaMS40C9kvns1mlDu
+  LhIhYpJ8UsCVt5snWo2N+M+6ANh5tpWdQnEK6zILh4tRbuzaiHgb
+  -----END RSA PRIVATE KEY-----
diff --git a/app/_data/entity_examples/config.yml b/app/_data/entity_examples/config.yml
@@ -58,6 +58,7 @@ formats:
       target:         '/upstreams/{upstream}/targets/'
       upstream:       '/upstreams/'
       workspace:      '/workspaces/'
+      certificate:     '/certificates/'
     plugin_endpoints:
       consumer:       '/consumers/{consumer}/plugins/'
       consumer_group: '/consumer_groups/{consumer_group}/plugins/'

diff --git a/app/_gateway_entities/ca-certificate.md b/app/_gateway_entities/ca-certificate.md
@@ -0,0 +1,34 @@
+---
+title: CA Certificates
+content_type: reference
+entities:
+  - ca-certificate
+
+description: A CA certificate object represents a trusted certificate authority. These objects are used by {{site.base_gateway}} to verify the validity of a client or server certificate.
+
+related_resources:
+  - text: Certificate entity
+    url: /gateway/entities/certificate
+  - text: Mutual TLS Authentication plugin
+    url: /plugins/mtls-auth
+
+tools:
+    - admin-api
+    - konnect-api
+    - kic
+    - deck
+    - terraform
+
+
+api_specs:
+    - gateway/admin-oss
+    - gateway/admin-ee
+    - konnect/control-planes-config
+
+schema:
+    api: gateway/admin-ee
+    path: /schemas/CA-Certificate
+
+---
+
+<!--This is being worked on in https://github.com/Kong/developer.konghq.com/pull/220-->
diff --git a/app/_gateway_entities/certificate.md b/app/_gateway_entities/certificate.md
@@ -0,0 +1,109 @@
+---
+title: Certificates
+content_type: reference
+entities:
+  - certificate
+
+description: A certificate object represents a public certificate, and can be optionally paired with the corresponding private key.
+
+related_resources:
+  - text: Set up {{site.base_gateway}} to serve an SSL certificate for API requests
+    url: /how-to/setup-gateway-to-serve-SSL-certificates
+  - text: CA Certificate entity
+    url: /gateway/entities/ca-certificate/
+
+tools:
+    - admin-api
+    - konnect-api
+    - kic
+    - deck
+    - terraform
+
+api_specs:
+    - gateway/admin-ee
+    - konnect/control-planes-config 
+    - gateway/admin-oss
+
+schema:
+    api: gateway/admin-ee
+    path: /schemas/Certificate
+
+faqs:
+  - q: What's the difference between the Certificate entity and the CA Certificate entity?
+    a: Certificates handle [SSL/TLS termination](/kic/tls-termination-passthrough) for encrypted requests and [CA Certificates](/gateway/entities/ca-certificate/) validate client or server certificates.
+  - q: Is the Certificate entity used in {{site.konnect_short_name}} for data plane nodes as well?
+    a: No, the data plane nodes use a [different certificate](/api/konnect/control-planes-config/).
+---
+
+## What is a Certificate?
+
+A Certificate object represents a public certificate, which is used to validate the sender's authorization and name. It can optionally be paired with the corresponding private key to initiate secure connections and encrypt sensitive data. 
+
+{{site.base_gateway}} can use Certificates in the following ways:
+* Handle [SSL/TLS termination](/kic/tls-termination-passthrough) for encrypted requests
+* Use as a trusted CA store when validating peer certificate of client or Service
+* Tie a certificate and key pair to one or more hostnames using the associated SNI object
+
+## Schema
+
+{% entity_schema %}
+
+## Set up a Certificate
+
+{% entity_example %}
+type: certificate
+data:
+    cert: |
+        -----BEGIN CERTIFICATE-----
+        MIID0DCCArigAwIBAgIBATANBgkqhkiG9w0BAQUFADB/MQswCQYDVQQGEwJGUjET
+        MBEGA1UECAwKU29tZS1TdGF0ZTEOMAwGA1UEBwwFUGFyaXMxDTALBgNVBAoMBERp
+        bWkxDTALBgNVBAsMBE5TQlUxEDAOBgNVBAMMB0RpbWkgQ0ExGzAZBgkqhkiG9w0B
+        CQEWDGRpbWlAZGltaS5mcjAeFw0xNDAxMjgyMDM2NTVaFw0yNDAxMjYyMDM2NTVa
+        MFsxCzAJBgNVBAYTAkZSMRMwEQYDVQQIDApTb21lLVN0YXRlMSEwHwYDVQQKDBhJ
+        bnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQxFDASBgNVBAMMC3d3dy5kaW1pLmZyMIIB
+        IjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvpnaPKLIKdvx98KW68lz8pGa
+        RRcYersNGqPjpifMVjjE8LuCoXgPU0HePnNTUjpShBnynKCvrtWhN+haKbSp+QWX
+        SxiTrW99HBfAl1MDQyWcukoEb9Cw6INctVUN4iRvkn9T8E6q174RbcnwA/7yTc7p
+        1NCvw+6B/aAN9l1G2pQXgRdYC/+G6o1IZEHtWhqzE97nY5QKNuUVD0V09dc5CDYB
+        aKjqetwwv6DFk/GRdOSEd/6bW+20z0qSHpa3YNW6qSp+x5pyYmDrzRIR03os6Dau
+        ZkChSRyc/Whvurx6o85D6qpzywo8xwNaLZHxTQPgcIA5su9ZIytv9LH2E+lSwwID
+        AQABo3sweTAJBgNVHRMEAjAAMCwGCWCGSAGG+EIBDQQfFh1PcGVuU1NMIEdlbmVy
+        YXRlZCBDZXJ0aWZpY2F0ZTAdBgNVHQ4EFgQU+tugFtyN+cXe1wxUqeA7X+yS3bgw
+        HwYDVR0jBBgwFoAUhMwqkbBrGp87HxfvwgPnlGgVR64wDQYJKoZIhvcNAQEFBQAD
+        ggEBAIEEmqqhEzeXZ4CKhE5UM9vCKzkj5Iv9TFs/a9CcQuepzplt7YVmevBFNOc0
+        +1ZyR4tXgi4+5MHGzhYCIVvHo4hKqYm+J+o5mwQInf1qoAHuO7CLD3WNa1sKcVUV
+        vepIxc/1aHZrG+dPeEHt0MdFfOw13YdUc2FH6AqEdcEL4aV5PXq2eYR8hR4zKbc1
+        fBtuqUsvA8NWSIyzQ16fyGve+ANf6vXvUizyvwDrPRv/kfvLNa3ZPnLMMxU98Mvh
+        PXy3PkB8++6U4Y3vdk2Ni2WYYlIls8yqbM4327IKmkDc2TimS8u60CT47mKU7aDY
+        cbTV5RDkrlaYwm5yqlTIglvCv7o=
+        -----END CERTIFICATE-----
+    id: b2f34145-0343-41a4-9602-4c69dec2f269
+    key: |
+        -----BEGIN RSA PRIVATE KEY-----
+        MIIEowIBAAKCAQEAvpnaPKLIKdvx98KW68lz8pGaRRcYersNGqPjpifMVjjE8LuC
+        oXgPU0HePnNTUjpShBnynKCvrtWhN+haKbSp+QWXSxiTrW99HBfAl1MDQyWcukoE
+        b9Cw6INctVUN4iRvkn9T8E6q174RbcnwA/7yTc7p1NCvw+6B/aAN9l1G2pQXgRdY
+        C/+G6o1IZEHtWhqzE97nY5QKNuUVD0V09dc5CDYBaKjqetwwv6DFk/GRdOSEd/6b
+        W+20z0qSHpa3YNW6qSp+x5pyYmDrzRIR03os6DauZkChSRyc/Whvurx6o85D6qpz
+        ywo8xwNaLZHxTQPgcIA5su9ZIytv9LH2E+lSwwIDAQABAoIBAFml8cD9a5pMqlW3
+        f9btTQz1sRL4Fvp7CmHSXhvjsjeHwhHckEe0ObkWTRsgkTsm1XLu5W8IITnhn0+1
+        iNr+78eB+rRGngdAXh8diOdkEy+8/Cee8tFI3jyutKdRlxMbwiKsouVviumoq3fx
+        OGQYwQ0Z2l/PvCwy/Y82ffq3ysC5gAJsbBYsCrg14bQo44ulrELe4SDWs5HCjKYb
+        EI2b8cOMucqZSOtxg9niLN/je2bo/I2HGSawibgcOdBms8k6TvsSrZMr3kJ5O6J+
+        77LGwKH37brVgbVYvbq6nWPL0xLG7dUv+7LWEo5qQaPy6aXb/zbckqLqu6/EjOVe
+        ydG5JQECgYEA9kKfTZD/WEVAreA0dzfeJRu8vlnwoagL7cJaoDxqXos4mcr5mPDT
+        kbWgFkLFFH/AyUnPBlK6BcJp1XK67B13ETUa3i9Q5t1WuZEobiKKBLFm9DDQJt43
+        uKZWJxBKFGSvFrYPtGZst719mZVcPct2CzPjEgN3Hlpt6fyw3eOrnoECgYEAxiOu
+        jwXCOmuGaB7+OW2tR0PGEzbvVlEGdkAJ6TC/HoKM1A8r2u4hLTEJJCrLLTfw++4I
+        ddHE2dLeR4Q7O58SfLphwgPmLDezN7WRLGr7Vyfuv7VmaHjGuC3Gv9agnhWDlA2Q
+        gBG9/R9oVfL0Dc7CgJgLeUtItCYC31bGT3yhV0MCgYEA4k3DG4L+RN4PXDpHvK9I
+        pA1jXAJHEifeHnaW1d3vWkbSkvJmgVf+9U5VeV+OwRHN1qzPZV4suRI6M/8lK8rA
+        Gr4UnM4aqK4K/qkY4G05LKrik9Ev2CgqSLQDRA7CJQ+Jn3Nb50qg6hFnFPafN+J7		
+        7juWln08wFYV4Atpdd+9XQECgYBxizkZFL+9IqkfOcONvWAzGo+Dq1N0L3J4iTIk
+        w56CKWXyj88d4qB4eUU3yJ4uB4S9miaW/eLEwKZIbWpUPFAn0db7i6h3ZmP5ZL8Q
+        qS3nQCb9DULmU2/tU641eRUKAmIoka1g9sndKAZuWo+o6fdkIb1RgObk9XNn8R4r
+        psv+aQKBgB+CIcExR30vycv5bnZN9EFlIXNKaeMJUrYCXcRQNvrnUIUBvAO8+jAe
+        CdLygS5RtgOLZib0IVErqWsP3EI1ACGuLts0vQ9GFLQGaN1SaMS40C9kvns1mlDu
+        LhIhYpJ8UsCVt5snWo2N+M+6ANh5tpWdQnEK6zILh4tRbuzaiHgb
+        -----END RSA PRIVATE KEY-----
+{% endentity_example %}
diff --git a/app/_how-tos/setup-gateway-to-serve-SSL-certificates.md b/app/_how-tos/setup-gateway-to-serve-SSL-certificates.md
@@ -0,0 +1,43 @@
+---
+title: Set up {{site.base_gateway}} to serve an SSL certificate for API requests
+content_type: how_to
+related_resources:
+  - text: Certificate entity
+    url: /gateway/entities/certificate
+
+products:
+    - gateway
+
+works_on:
+    - on-prem
+    - konnect
+
+entities: 
+  - certificate
+  - sni
+
+tags:
+    - networking
+
+tldr:
+    q: How do I set up {{site.base_gateway}} to serve an SSL certificate for API requests?
+    a: Generate a custom certificate/key pair using a Certificate Authority (CA) you create. Create a key for your desired host (`kong.lan`) and a CSR, setting the common name to match the hostname. Create a `kong.lan.ext` file and use the file to create a certificate signed with our CA. Then, upload the certificate and key to {{site.base_gateway}} and create an `kong.lan` SNI entity.
+
+tools:
+    - deck
+
+cleanup:
+  inline:
+    - title: Clean up Konnect environment
+      include_content: cleanup/platform/konnect
+      icon_url: /assets/icons/gateway.svg
+    - title: Destroy the {{site.base_gateway}} container
+      include_content: cleanup/products/gateway
+      icon_url: /assets/icons/gateway.svg
+---
+
+@todo
+
+<!--content notes:
+- Use content from this KB: https://support.konghq.com/support/s/article/How-to-setup-Kong-to-serve-an-SSL-certificate-for-API-requests
+-->
diff --git a/app/_includes/components/entity_example/format/ui.md b/app/_includes/components/entity_example/format/ui.md
@@ -61,6 +61,20 @@ The following creates a new Upstream with basic configuration:
 3. Enter a unique name for the Upstream. For example: `{{ include.presenter.data['name'] }}`.
 4. Click **Save**.
 {% when workspace %}
+{% when 'certificate' %}
+The following creates a new Certificate with basic configuration:
+
+1. In Kong Manager or Gateway Manager, go to **Certificates**.
+2. On the Certificates tab, click **New Certificate**.
+3. In the **Cert** field, enter the PEM-encoded public certificate:
+    ```
+    {{ include.presenter.data['cert'] }}
+    ```
+4. In the **Key** field, enter the PEM-encoded private key:
+    ```
+    {{ include.presenter.data['key'] }}
+    ```
+5. Click **Save**.
 {% else %}
 {% endcase %}
 {% endif %}
diff --git a/app/_landing_pages/gateway/entities.yaml b/app/_landing_pages/gateway/entities.yaml
@@ -53,7 +53,12 @@ rows:
       - type: entity_card
         config:
           entity: workspace
+  - columns:
     - blocks:
       - type: entity_card
         config:
           entity: event-hook
+    - blocks:
+      - type: entity_card
+        config:
+          entity: certificate
diff --git a/app/kic/tls-termination-passthrough.md b/app/kic/tls-termination-passthrough.md
@@ -0,0 +1,19 @@
+---
+title: TLS Termination / Passthrough
+
+description: "The Gateway API supports both TLS termination and TLS passthrough."
+
+content_type: reference
+layout: reference
+
+products:
+  - gateway
+
+related_resources:
+  - text: Certificate entity
+    url: /gateway/entities/certificate/
+---
+
+@TODO 
+
+Contains content from https://docs.konghq.com/kubernetes-ingress-controller/latest/guides/services/tls/