From 4e0749e6cb8bde21eb4ad8d4407bd0e9455230a8 Mon Sep 17 00:00:00 2001 From: Navendu Pottekkat Date: Fri, 28 Oct 2022 14:54:47 +0530 Subject: [PATCH] docs: update "ApisixTls" and "ApisixClusterConfig" (#1414) --- .../latest/concepts/apisix_cluster_config.md | 43 +++++++++---------- docs/en/latest/concepts/apisix_tls.md | 28 +++++++----- 2 files changed, 37 insertions(+), 34 deletions(-) diff --git a/docs/en/latest/concepts/apisix_cluster_config.md b/docs/en/latest/concepts/apisix_cluster_config.md index 4e9b5f75d8..79c48e7d87 100644 --- a/docs/en/latest/concepts/apisix_cluster_config.md +++ b/docs/en/latest/concepts/apisix_cluster_config.md @@ -1,5 +1,10 @@ --- title: ApisixClusterConfig +keywords: + - APISIX ingress + - Apache APISIX + - ApisixClusterConfig +description: Guide to using ApisixClusterConfig custom Kubernetes resource. --- -`ApisixClusterConfig` is a CRD resource which used to describe an APISIX cluster, currently it's not a required -resource but its existence can enrich an APISIX cluster, for instance, enabling cluster-wide monitoring, rate limiting and so on. +`ApisixClusterConfig` is a Kubernetes CRD resource that can be used to describe an APISIX cluster and manage it. -monitoring features like collecting [Prometheus](https://prometheus.io/) metrics -and [skywalking](https://skywalking.apache.org/) spans +## Monitoring -Monitoring ----------- +By default, monitoring is not enabled in an APISIX cluster. You can enable it by creating an `ApisixClusterConfig` resource. -By default, monitoring are not enabled for the APISIX cluster, this is not favorable -if you'd like to learn the real running status of your cluster. In such a case, you -could create a `ApisixClusterConfig` to enable these features explicitly. +The example below enabled [Prometheus](http://apisix.apache.org/docs/apisix/plugins/prometheus) and [SkyWalking](http://apisix.apache.org/docs/apisix/plugins/skywalking) for the "default" APISIX cluster (in [multi-cluster deployments](#multi-cluster-management)). ```yaml apiVersion: apisix.apache.org/v2 @@ -48,14 +48,11 @@ spec: sampleRatio: 0.5 ``` -The above example enables both the Prometheus and Skywalking for the APISIX cluster which name is "default". -Please see [Prometheus in APISIX](http://apisix.apache.org/docs/apisix/plugins/prometheus) and [Skywalking in APISIX](http://apisix.apache.org/docs/apisix/plugins/skywalking) for the details. +## Admin configuration -Admin Config ------------- +Instead of changing the deployment or pod definition files, you can use the `ApisixClusterConfig` resource to change the admin configurations. -The default APISIX cluster is configured through command line options like `--default-apisix-cluster-xxx`. They are constant in apisix-ingress-controller's lifecycle, you have to change the definition -of Deployment or Pod template. Now with the help of `ApisixClusterConfig`, you can change some administrative fields on it. +The example below configures the base URL and admin key for the APISIX cluster "default": ```yaml apiVersion: apisix.apache.org/v2 @@ -68,14 +65,14 @@ spec: adminKey: "123456" ``` -The above `ApisixClusterConfig` sets the base url and admin key for the APISIX cluster `"default"`. Once this -resource is processed, resources like Route, Upstream and others will be pushed to the new address with the new admin key (for authentication). +Once configured, other resources (Route, Upstream, etc) will be forwarded to the new address with the new admin key. -Multiple Clusters Management ----------------------------- +## Multi-cluster management -`ApisixClusterConfig` is also designed for supporting multiple clusters management, but currently this function IS NOT ENABLED YET. -Only the `ApisixClusterConfig` with the same named configured in `--default-apisix-cluster-name` option will be handled by apisix-ingress-controller, other instances will be neglected. +The `ApisixClusterConfig` resource can also be used to manage multiple APISIX clusters. This function is **not enabled currently** and it can only manage the cluster configured through `--default-apisix-cluster-name` attribute. -The current delete event for `ApisixClusterConfig` doesn't mean the apisix-ingress-controller will lose the view of the corresponding APISIX cluster but -resetting all the features on it, so the running of APISIX cluster is not influenced by this event. +:::note + +Deleting an `ApisixClusterConfig` resource will only reset the configurations of an APISIX cluster and will not affect its running. + +::: diff --git a/docs/en/latest/concepts/apisix_tls.md b/docs/en/latest/concepts/apisix_tls.md index 20c80eed4c..5cd73fac4d 100644 --- a/docs/en/latest/concepts/apisix_tls.md +++ b/docs/en/latest/concepts/apisix_tls.md @@ -1,7 +1,11 @@ --- title: ApisixTls +keywords: + - APISIX ingress + - Apache APISIX + - ApisixTls +description: Guide to using ApisixTls custom Kubernetes resource. --- - -ApisixTls associates with a Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) resource and -generates an [APISIX SSL](http://apisix.apache.org/docs/apisix/admin-api#ssl) object. It asks the -Secret must have two keys `cert` and `key`, which used to store the certificate and private key in -PEM format respectively. +`ApisixTls` is a Kubernetes CRD object used to create an [APISIX SSL object](http://apisix.apache.org/docs/apisix/admin-api#ssl). It uses a [Kubernetes secret](https://kubernetes.io/docs/concepts/configuration/secret/) with two keys, `cert` containing the certificate, and `key` containing the private key in PEM format. + +See [reference](https://apisix.apache.org/docs/ingress-controller/references/apisix_tls_v2) for the full API documentation. + +The example below shows how you can configure an `ApisixTls` resource: -```shell +```yaml apiVersion: apisix.apache.org/v2 kind: ApisixTls metadata: @@ -39,9 +44,10 @@ spec: namespace: default ``` -Note the `hosts` field should be written carefully, it's used by Apache APISIX to match the -correct certificate, what's more, it also should be matched with the [Server Name Indication](https://www.globalsign.com/en/blog/what-is-server-name-indication#:~:text=Server%20Name%20Indication%20(SNI)%20allows,in%20the%20CLIENT%20HELLO%20message) -extension in TLS, or the TLS handshaking might fail. +:::info IMPORTANT + +Make sure that the `hosts` field is accurate. APISIX uses the `host` field to match the correct certificate. It should also match the [Server Name Indication](https://www.globalsign.com/en/blog/what-is-server-name-indication#:~:text=Server%20Name%20Indication%20(SNI)%20allows,in%20the%20CLIENT%20HELLO%20message) extension in TLS, or the TLS handshake might fail. + +::: -The apisix-ingress-controller will watch Secret resources that referred by ApisixTls objects, once a -Secret changed, apisix-ingress-controller will re translate all referred ApisixTls objects, converting them to APISIX SSL resources ultimately. +APISIX Ingress will watch the secret resources referred by `ApisixTls` objects and re-translates it to APISIX resources if they are changed.