diff --git a/app/_data/docs_nav_kgo_1.4.x.yml b/app/_data/docs_nav_kgo_1.4.x.yml index 802b0df8a7aa..71aa4557449c 100644 --- 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 index d29952831d88..522d06e1e6a9 100644 --- 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 index 4e5a732b0c6b..87bd38995ea5 100644 --- 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 %} +{% if_version gte:1.1.x lte:1.3.x %} +{% assign gwapi_version = "1.0.0" %} +{% endif %} +### Install CRDs + +If you want to use Gateway API resources please 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 index bc3634fac019..97611cf1c2f1 100644 --- 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 index 923eb6214382..1c58b2360735 100644 --- 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 index 9599a7672eaf..f0a56c7f1184 100644 --- 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 new file mode 100644 index 000000000000..5793aba1bbcb --- /dev/null +++ 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 (e.g. for securing Kong's Admin API). +This CA certificate is being 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 + +In order 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 also specify the private key algorithm used to sign the certificates by using 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