membphis commented on code in PR #11604: URL: https://github.com/apache/apisix/pull/11604#discussion_r1778047926
########## docs/en/latest/plugins/attach-consumer-label.md: ########## @@ -0,0 +1,180 @@ +--- +title: attach-consumer-label +keywords: + - Apache APISIX + - API Gateway + - API Consumer +description: This article describes the Apache APISIX attach-consumer-label plugin, which you can use to pass custom consumer labels to upstream services. +--- + +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +--> + +## Description + +The `attach-consumer-label` plugin attaches custom consumer-related labels, in addition to `X-Consumer-Username` and `X-Credential-Indentifier`, to authenticated requests, for upstream services to differentiate between consumers and implement additional logics. + +## Attributes + +| Name | Type | Required | Default | Valid values | Description | +|----------|--------|----------|---------|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| headers | object | True | | | Key-value pairs of consumer labels to be attached to request headers, where key is the request header name, such as `X-Consumer-Role`, and the value is a reference to the custom label key, such as `$role`. Note that the value should always start with a dollar sign (`$`). If a referenced consumer value is not configured on the consumer, the corresponding header will not be attached to the request. | + +## Enable Plugin + +The following example demonstrates how you can attach custom labels to request headers before authenticated requests are forwarded to upstream services. If the request is rejected, you should not see any consumer labels attached to request headers. If a certain label value is not configured on the consumer but referenced in the `attach-consumer-label` plugin, the corresponding header will also not be attached. + +:::note + +You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command: + +```bash +admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g') +``` + +::: + +Create a consumer `john` with custom labels: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers"; -X PUT \ + -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -d '{ + "username": "john", + # highlight-start + "labels": { + // Annotate 1 + "department": "devops", + // Annotate 2 + "company": "api7" + } + # highlight-end + }' +``` + +❶ Label the `department` information for the consumer. Review Comment: I prefer the Markdown style, which is easy to render by different Markdown tools ``` 1. xxxx 2. xxxx 3. xxxx ########## docs/zh/latest/plugins/attach-consumer-label.md: ########## @@ -0,0 +1,180 @@ +--- +title: attach-consumer-label +keywords: + - Apache APISIX + - API 网关 + - API Consumer +description: 本文介绍了 Apache APISIX attach-consumer-label 插件的相关操作，你可以使用此插件向上游服务传递自定义的 Consumer labels。 +--- + +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +--> + +## 描述 + +`attach-consumer-label` 插件在 X-Consumer-Username 和 X-Credential-Indentifier 之外，还将自定义的消费者相关标签附加到经过身份验证的请求，以便上游服务区分消费者并实现额外的逻辑。 + +## 属性 + +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +|----------|--------|--------|----------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------| +| headers | object | 是 | | | 要附加到请求标头的 Consumer 标签的键值对，其中键是请求标头名称，例如 "X-Consumer-Role"，值是对客户标签键的引用，例如 "$role"。请注意，该值应始终以美元符号 (`$`) 开头。如果 Consumer 上没有配置引用的值，则相应的标头将不会附加到请求中。 | + +## 启用插件 + +下面的示例演示了如何在通过身份验证的请求转发到上游服务之前，将自定义标签附加到请求标头。如果请求被拒绝，就不会在请求标头上附加任何消费者标签。如果某个标签值未在消费者上配置，但在“attach-consumer-label”插件中被引用，相应的标头也不会被附加。 + +:::note + +您可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量： + +```bash +admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g') +``` + +::: + +创建一个有自定义标签的 Consumer `john`: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers"; -X PUT \ + -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -d '{ + "username": "john", + # highlight-start + "labels": { + // Annotate 1 + "department": "devops", + // Annotate 2 + "company": "api7" + } + # highlight-end + }' +``` + +❶ Consumer 的 `department` 标签信息。 Review Comment: ditto ########## docs/zh/latest/plugins/attach-consumer-label.md: ########## @@ -0,0 +1,180 @@ +--- +title: attach-consumer-label +keywords: + - Apache APISIX + - API 网关 + - API Consumer +description: 本文介绍了 Apache APISIX attach-consumer-label 插件的相关操作，你可以使用此插件向上游服务传递自定义的 Consumer labels。 +--- + +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +--> + +## 描述 + +`attach-consumer-label` 插件在 X-Consumer-Username 和 X-Credential-Indentifier 之外，还将自定义的消费者相关标签附加到经过身份验证的请求，以便上游服务区分消费者并实现额外的逻辑。 + +## 属性 + +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +|----------|--------|--------|----------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------| +| headers | object | 是 | | | 要附加到请求标头的 Consumer 标签的键值对，其中键是请求标头名称，例如 "X-Consumer-Role"，值是对客户标签键的引用，例如 "$role"。请注意，该值应始终以美元符号 (`$`) 开头。如果 Consumer 上没有配置引用的值，则相应的标头将不会附加到请求中。 | + +## 启用插件 + +下面的示例演示了如何在通过身份验证的请求转发到上游服务之前，将自定义标签附加到请求标头。如果请求被拒绝，就不会在请求标头上附加任何消费者标签。如果某个标签值未在消费者上配置，但在“attach-consumer-label”插件中被引用，相应的标头也不会被附加。 + +:::note + +您可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量： + +```bash +admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g') +``` + +::: + +创建一个有自定义标签的 Consumer `john`: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers"; -X PUT \ + -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -d '{ + "username": "john", + # highlight-start + "labels": { + // Annotate 1 + "department": "devops", + // Annotate 2 + "company": "api7" + } + # highlight-end + }' +``` + +❶ Consumer 的 `department` 标签信息。 + +❷ Consumer 的 `company` 标签信息。 + +为 Consumer `john` 配置 `key-auth`: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers/john/credentials"; -X PUT \ + -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -d '{ + "id": "cred-john-key-auth", + "plugins": { + "key-auth": { + "key": "john-key" + } + } + }' +``` + +创建路由并启用 `key-auth` 和 `attach-consumer-label` 插件： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${ADMIN_API_KEY}" \ + -d '{ + "id": "attach-consumer-label-route", + "uri": "/get", + "plugins": { + "key-auth": {}, + # highlight-start + "attach-consumer-label": { + "headers": { + // Annotate 1 + "X-Consumer-Department": "$department", + // Annotate 2 + "X-Consumer-Company": "$company", + // Annotate 3 + "X-Consumer-Role": "$role" + } + } + # highlight-end + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +❶ 将 Consumer 标签 `department` 的值附加到请求头的 `X-Consumer-Department` 字段。 Review Comment: ditto -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
