Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update "FAQ" page #1437

Merged
merged 3 commits into from
Nov 11, 2022
Merged

docs: update "FAQ" page #1437

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2f5c64b
docs: update "FAQ" page
pottekkat Nov 4, 2022
2116c3b
update markdown-lint version
pottekkat Nov 11, 2022
79adc37
fix unrelated link check error
pottekkat Nov 11, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 37 additions & 35 deletions docs/en/latest/FAQ.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,12 @@
---
title: FAQ
keywords:
- APISIX ingress
- Apache APISIX
- Kubernetes ingress
- FAQ
description: Answers to frequently asked questions about APISIX Ingress.
---

<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
Expand All @@ -21,68 +26,65 @@ title: FAQ
#
-->

### 1. How to bind Service and Upstream

All resource objects are uniquely determined by the namespace / name / port combination Id. If the combined Id is the same, the `service` and `upstream` will be considered as a binding relationship.

### 2. When modifying a CRD, how do other binding objects perceive it
## How do I bind a Service with an Upstream?

This is a cascading update problem, see for details [apisix-ingress-controller Design ideas](./design.md)
All resources are uniquely identified by the namespace/name/port combination. If this combination is the same, the Service and the Upstream will be binded.

### 3. Can I mix CRDs and admin api to define routing rules
## While modifying a CRD, how does the binded resources perceive it?

No, currently we are implementing one-way synchronization, that is, CRDs file -> Apache AIPSIX. If the configuration is modified separately through admin api, it will not be synchronized to CRDs in Kubernetes.
This is a cascading update problem. See [Design](./design.md) for more details.

This is because CRDs are generally declared in the file system, and Apply to enter Kubernetes etcd, we follow the definition of CRDs and synchronize to Apache Apisix Data Plane, but the reverse will make the situation more complicated.
## Can I use both CRDs and the Admin API together to configure Routes?

### 4. Why there are some error logs like "list upstreams failed, err: http get failed, url: blahblahblah, err: status: 401"
No. CRDs are declarative and when applied they are translated to APISIX configuration. Configuring APISIX through Admin API would not change the CRDs.

So far apisix-ingress-controller doesn't support set admin_key for Apache APISIX, so when you deploy your APISIX cluster, admin_key should be removed from config.
## Why is there an error like "list upstreams failed, err: http get failed, url: httpbin.org, err: status: 401"?

Note since APISIX have two configuration files, the first is config.yaml, which contains the user specified configs, the other is config-default.yaml, which has all default items, config items in these two files will be merged. So admin_key in both files should be removed. You can customize these two configuration files and mount them to APISIX deployment.
APISIX Ingress controller does not support configuring `admin_key` for APISIX. Removing `admin_key` from both your configuration file (`config.yaml` and `config-default.yaml`) when deploying APISIX will fix this issue.

### 5. Failed to create route with `ApisixRoute`
<!-- ### 5. Failed to create route with `ApisixRoute`

When `apisix-ingress-controller` creates a route with CRD, it checks the `Endpoint` resources in Kubernetes (matched by namespace_name_port). If the corresponding endpoint information is not found, the route will not be created and wait for the next retry.

Tips: The failure caused by empty upstream nodes is a limitation of Apache APISIX, related [issue](https://github.com/apache/apisix/issues/3072)
Tips: The failure caused by empty upstream nodes is a limitation of Apache APISIX, related [issue](https://github.com/apache/apisix/issues/3072) -->

### 6. What is the retry rule of `apisix-ingress-controller`
## How does APISIX Ingress controller retry?

If an error occurs during the process of `apisix-ingress-controller` parsing CRD and distributing the configuration to APISIX, a retry will be triggered.
If an error occurs while parsing the CRD and translating the configuration to APISIX, a retry will be triggered.

The delayed retry method is adopted. After the first failure, it is retried once per second. After 5 retries are triggered, the slow retry strategy will be enabled, and the retry will be performed every 1 minute until it succeeds.
Delays are used while retrying. It retries once per second at first and after five retries, it will be decreased to one retry per minute until it succeeds.

### 7. What if the CRDs need to be updated when you upgrading apisix-ingress-controller
## How do I update the CRDs when updating APISIX Ingress controller?

CRDs upgrading is special as helm chart will skip to apply these resources when they already exist.
The Helm chart will skip applying these CRDs if they already exist.

> With the arrival of Helm 3, we removed the old crd-install hooks for a more simple methodology. There is now a special directory called crds that you can create in your chart to hold your CRDs. These CRDs are not templated, but will be installed by default when running a helm install for the chart. If the CRD already exists, it will be skipped with a warning. If you wish to skip the CRD installation step, you can pass the --skip-crds flag.

In such a case, you may need to apply these CRDs by yourself.
In such cases, you can apply the CRDs manually:

```shell
kubectl apply -k samples/deploy/crd/
```

### 8. Why apisix-ingress-controller reports similar errors when running: no matches for kind "ApisixRoute" in version "apisix.apache.org/v2beta3"
:::note

The version `v2beta3` is the newest version of resource `ApisixRoute`. You need to check if the CRD definition file is up to date.
With Helm 3, old CRD-install hooks were replaced by a simpler system. You can now create a special directory called `crds` in your charts for holding CRDs.

```shell
kubectl get crd apisixroutes.apisix.apache.org -o jsonpath='{ .spec.versions[*].name }' -A
```
These CRDs are not templated but will be installed by default when running `helm install`. If the CRD already exists, it will be skipped with a warning. You can skip the CRD installation step by passing the `--skip-crds` flag.

:::

If you can not find `v2beta3` in `ApisixRoute` definition file. Please apply the latest version of `ApisixRoute`.
## Why is there an error like "no matches for kind "ApisixRoute" in version "apisix.apache.org/v2beta3"" when I try to create a Route?

Ref to FAQ #7.
Make sure that you have the correct version of the CRDs installed in your cluster (see [updating CRDs](#how-do-i-update-the-crds-when-updating-apisix-ingress-controller)). `ApisixRoute` has two versions: `v2beta3` and `v2`.

### 9. Modify the Admin API key in APISIX-Ingress
Also check your `ApisixRoute` definition for the correct version by running:

Usually, you need to modify the Admin API key to protect Apache APISIX. Please refer to this [link](https://apisix.apache.org/docs/apisix/installation-guide/#updating-admin-api-key) to simply change Apache APISIX.
```shell
kubectl get crd apisixroutes.apisix.apache.org -o jsonpath='{ .spec.versions[*].name }' -A
```

However, in apisix-ingress-controller, if we need to change the Admin API key, we also need to change the Admin API key in apisix-ingress-controller. There are two different ways to implement the requirements here.
## How do I modify the Admin API key in APISIX Ingress?

For the first method, we need to modify the Admin API credentials values in both the `apisix/values.yaml` and `apisix/apisix-ingress-controller/values.yaml` files. You can refer to these two links(apisix's [values.yaml](https://github.com/apache/apisix-helm-chart/blob/57cdbe461765cd49af2195cc6a1976cc55262e9b/charts/apisix/values.yaml#L181) && apisix-ingress-controller's [values.yaml](https://github.com/apache/apisix-helm-chart/blob/57cdbe461765cd49af2195cc6a1976cc55262e9b/charts/apisix-ingress-controller/values.yaml#L128)).
You can change the Admin API key in two ways:

Another method, you can just pass `--set ingress-controller.config.apisix.adminKey=<Your new admin key> --set admin.credentials.admin=<Your new admin key>` to `helm install` command.
1. Modify the key in both [apisix/values.yaml](https://github.com/apache/apisix-helm-chart/blob/57cdbe461765cd49af2195cc6a1976cc55262e9b/charts/apisix/values.yaml#L181) and [apisix/apisix-ingress-controller/values.yaml](https://github.com/apache/apisix-helm-chart/blob/57cdbe461765cd49af2195cc6a1976cc55262e9b/charts/apisix-ingress-controller/values.yaml#L128) files.
2. You can also set this imperatively by passing the flag `--set ingress-controller.config.apisix.adminKey=<new key> --set admin.credentials.admin=<new key>` to the `helm install` command.