kgo: add guide for customizing cluster CA (#8386)

* kgo: add guide for customizing cluster CA * minor grammar & punctuation edits --------- Co-authored-by: lena-larionova <[email protected]>
Kong · Feb 1, 2025 · 489be77 · 489be77
1 parent 5f29432
commit 489be77
Show file tree

Hide file tree

Showing 7 changed files with 83 additions and 14 deletions.
diff --git a/app/_data/docs_nav_kgo_1.4.x.yml b/app/_data/docs_nav_kgo_1.4.x.yml
@@ -74,6 +74,10 @@ items:
                 url: /production/monitoring/status/gateway/
       - text: Upgrade Gateway Operator
         url: /production/upgrade/gateway-operator/
+      - text: Certificates
+        items:
+          - text: Using custom CA for signing operator certificates
+            url: /production/certificates/custom_ca
   - title: Guides
     icon: /assets/images/icons/documentation/icn-solution-guide.svg
     items:

diff --git a/app/_data/docs_nav_kgo_1.5.x.yml b/app/_data/docs_nav_kgo_1.5.x.yml
@@ -74,6 +74,10 @@ items:
                 url: /production/monitoring/status/gateway/
       - text: Upgrade Gateway Operator
         url: /production/upgrade/gateway-operator/
+      - text: Certificates
+        items:
+          - text: Using custom CA for signing operator certificates
+            url: /production/certificates/custom_ca
   - title: Guides
     icon: /assets/images/icons/documentation/icn-solution-guide.svg
     items:

diff --git a/app/_includes/md/kgo/prerequisites.md b/app/_includes/md/kgo/prerequisites.md
@@ -7,12 +7,24 @@
 ## Prerequisites
 {% endunless %}
 
-{% if include.experimental %}
-### Install CRDs
-{% assign gwapi_version = "1.0.0" %}
-{% if include.release.value == "1.0.x" %}
+{% if include.install_crds %}
+{% assign gwapi_version = "1.2.1" %}
+{% if_version eq:1.0.x %}
 {% assign gwapi_version = "0.8.1" %}
-{% endif %}
+{% endif_version %}
+{% if_version gte:1.1.x lte:1.3.x %}
+{% assign gwapi_version = "1.0.0" %}
+{% endif_version %}
+### Install CRDs
+
+If you want to use Gateway API resources, run this command:
+
+```shell
+kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v{{ gwapi_version }}/standard-install.yaml
+```
+
+{% if include.experimental %}
+#### Gateway API experimental CRDs
 
 If you want to use experimental resources and fields such as `TCPRoute`s and `UDPRoute`s, please run this command.
 
@@ -22,16 +34,19 @@ kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/downloa
 {% endif %}
 
 {% if include.aiGateway %}
+#### `AIGateway`
+
 The `AIGateway` feature is an **alpha** release, and needs additional CRDs installed:
 
 ```bash
 kubectl apply -f {{site.links.web}}/assets/gateway-operator/ai-gateway-crd.yaml --server-side
 ```
 {% endif %}
+{% endif %}
 
 ### 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
     kconfCRDs=include.kconfCRDs
     konnectEntities=include.konnectEntities
     aiGateway=include.aiGateway

diff --git a/app/_includes/snippets/gateway-operator/install_with_helm.md b/app/_includes/snippets/gateway-operator/install_with_helm.md
@@ -1,5 +1,8 @@
 {% assign kgo_version = include.release | replace: ".x", "" %}
+{% assign unreleased = false %}
+
 {% if include.release.label == "unreleased" %}
+{% assign unreleased = true %}
 {% assign kgo_version = "nightly" %}
 {% endif %}
 
@@ -13,7 +16,9 @@ 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 }}{% if include.kconfCRDs %} \
+helm upgrade --install kgo kong/gateway-operator -n kong-system --create-namespace {% if unreleased %}\
+  --set image.repository=kong/nightly-gateway-operator{% endif %} \
+  --set image.tag={{ kgo_version }}{% if include.kconfCRDs %} \
   --set kubernetes-configuration-crds.enabled=true{% endif %}{% if include.konnectEntities %} \
   --set env.ENABLE_CONTROLLER_KONNECT=true{% endif %}{% if include.aiGateway %} \
   --set env.ENABLE_CONTROLLER_AIGATEWAY=true{% endif %}{% if include.kongPluginInstallation %} \

diff --git a/app/_src/gateway-operator/get-started/kic/create-gateway.md b/app/_src/gateway-operator/get-started/kic/create-gateway.md
@@ -22,7 +22,7 @@ chapter: 2
 > in order to get your `Gateway` up and running.
 {% endif_version %}
 
-Creating `GatewayClass` and `Gateway` resources in Kubernetes causes {{ site.kgo_product_name }} to create a {{ site.kic_product_name }} and {{ site.base_gateway }} deployment. 
+Creating `GatewayClass` and `Gateway` resources in Kubernetes causes {{ site.kgo_product_name }} to create a {{ site.kic_product_name }} and {{ site.base_gateway }} deployment.
 
 ## GatewayConfiguration
 
@@ -38,7 +38,7 @@ If you are creating a KIC in {{site.konnect_short_name}} deployment, you need to
 To get the endpoint and the authentication details of the data plane.
 1. [Log in to {{ site.konnect_short_name }}](https://cloud.konghq.com/login).
 1. Navigate to {% konnect_icon runtimes %} [**Gateway Manager**](https://cloud.konghq.com/us/gateway-manager), click **New Control Plane** and select **{{ site.kic_product_name }}**.
-1. Enter a name for your new control plane 
+1. Enter a name for your new control plane.
 1. In the _Connect to KIC_ section, click **Generate Script**.
 1. Click **Generate Certificate** in step 3.
 1. Save the contents of **Cluster Certificate** in a file named `tls.crt`. Save the contents of **Cluster Key** in a file named `tls.key`.

diff --git a/app/_src/gateway-operator/get-started/kic/install.md b/app/_src/gateway-operator/get-started/kic/install.md
@@ -18,8 +18,4 @@ You can configure your `GatewayClass` and `Gateway` objects in a vendor independ
 
 This means that CRDs for both the Gateway API and {{ site.kic_product_name }} have to be installed.
 
-```bash
-kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml
-```
-
-{% include md/kgo/prerequisites.md disable_accordian=true version=page.version release=page.release %}
+{% include md/kgo/prerequisites.md disable_accordian=true version=page.version release=page.release install_crds=true %}
diff --git a/app/_src/gateway-operator/production/certificates/custom_ca.md b/app/_src/gateway-operator/production/certificates/custom_ca.md
@@ -0,0 +1,45 @@
+---
+title: Custom CA Certificates
+---
+
+{{ site.kgo_product_name }} uses a CA certificate to sign the certificates used by the `ControlPlane` and `DataPlane` components (for example, for securing Kong's Admin API).
+This CA certificate is retrieved from a Kubernetes Secret as configured via `--cluster-ca-secret` and `--cluster-ca-secret-namespace` flags.
+
+By default, the operator uses a self-signed CA certificate generated during the startup process.
+However, you can provide your own CA certificate to the operator by creating a Kubernetes `Secret` with the CA certificate.
+
+## Create a Kubernetes Secret
+
+To provide your own CA certificate to the operator, you need to create a Kubernetes `Secret` containing the CA certificate and key.
+
+This `Secret` has to contain the following fields:
+
+- `tls.crt`: The CA certificate
+- `tls.key`: The private key of the CA certificate
+
+{% if_version gte: 1.5.x %}
+### Configure the private key algorithm
+
+You can specify the private key algorithm used to sign the certificates with the `--cluster-ca-key-type` flag.
+
+It currently supports the following values:
+
+- `ecdsa`
+- `rsa`
+
+When this flag is set to `rsa`, you can also set the `--cluster-ca-key-size` flag to specify the size of the RSA key.
+
+{% endif_version %}
+
+### Supported private key algorithms
+
+Operator supports the following private key algorithms, which can be used to sign the certificates:
+
+- ECDSA: When this algorithm is used, Operator will use the [`ECDSAWithSHA256`][gopkg_ecdsa_sha256]
+  signature algorithm to sign the certificates.
+{% if_version gte: 1.5.x %}
+- RSA: When this algorithm is used, Operator will use the [`SHA256WithRSA`][gopkg_rsa_sha256] signature algorithm to sign the certificates.
+{% endif_version %}
+
+[gopkg_ecdsa_sha256]: https://pkg.go.dev/crypto/x509#ECDSAWithSHA256
+[gopkg_rsa_sha256]: https://pkg.go.dev/crypto/x509#SHA256WithRSA