kong系列:admin-api使用

部署好kong之后,则需要将我们自己的接口加入到kong中管理,kong提供了比较全面的restful api,每个版本会有所不同,下面的记录基于kong v0.14.x

kong的8001端口是resful admin api,服务、路由、配置都是通过这个端口进行管理,所以部署好之后页面可以直接访问localhost:8001

参考: https://docs.konghq.com/0.14.x/admin-api/#add-service

一、Retrieve node information(介绍节点信息)

获取kong节点的通用详细信息

1,查询节点信息

curl  http://localhost:8001

Endpoint

{
    "plugins": {
        "enabled_in_cluster": [],
        "available_on_server": {
            "response-transformer": true,
            "oauth2": true,
            "acl": true,
            "correlation-id": true,
            "pre-function": true,
            "jwt": true,
            "cors": true,
            "ip-restriction": true,
            "basic-auth": true,
            "key-auth": true,
            "rate-limiting": true,
            "request-transformer": true,
            "http-log": true,
            "file-log": true,
            "hmac-auth": true,
            "ldap-auth": true,
            "datadog": true,
            "tcp-log": true,
            "zipkin": true,
            "post-function": true,
            "request-size-limiting": true,
            "bot-detection": true,
            "syslog": true,
            "loggly": true,
            "azure-functions": true,
            "udp-log": true,
            "response-ratelimiting": true,
            "aws-lambda": true,
            "statsd": true,
            "prometheus": true,
            "request-termination": true
        }
    },
    "tagline": "Welcome to kong",
    "configuration": {
        "plugins": [
            "bundled"
        ],
        "admin_ssl_enabled": true,
        "lua_ssl_verify_depth": 1,
        "trusted_ips": {},
        "prefix": "/usr/local/kong",
        "loaded_plugins": {
            "response-transformer": true,
            "request-termination": true,
            "prometheus": true,
            "ip-restriction": true,
            "pre-function": true,
            "jwt": true,
            "cors": true,
            "statsd": true,
            "basic-auth": true,
            "key-auth": true,
            "ldap-auth": true,
            "aws-lambda": true,
            "http-log": true,
            "response-ratelimiting": true,
            "hmac-auth": true,
            "request-size-limiting": true,
            "datadog": true,
            "tcp-log": true,
            "zipkin": true,
            "post-function": true,
            "bot-detection": true,
            "acl": true,
            "loggly": true,
            "syslog": true,
            "azure-functions": true,
            "udp-log": true,
            "file-log": true,
            "request-transformer": true,
            "correlation-id": true,
            "rate-limiting": true,
            "oauth2": true
        },
        "cassandra_username": "kong",
        "admin_ssl_cert_csr_default": "/usr/local/kong/ssl/admin-kong-default.csr",
        "ssl_cert_key": "/usr/local/kong/ssl/kong-default.key",
        "admin_ssl_cert_key": "/usr/local/kong/ssl/admin-kong-default.key",
        "dns_resolver": {},
        "pg_user": "kong",
        "mem_cache_size": "128m",
        "cassandra_data_centers": [
            "dc1:2",
            "dc2:3"
        ],
        "nginx_admin_directives": {},
        "custom_plugins": {},
        "pg_host": "127.0.0.1",
        "nginx_acc_logs": "/usr/local/kong/logs/access.log",
        "proxy_listen": [
            "0.0.0.0:8000",
            "0.0.0.0:8443 ssl"
        ],
        "client_ssl_cert_default": "/usr/local/kong/ssl/kong-default.crt",
        "ssl_cert_key_default": "/usr/local/kong/ssl/kong-default.key",
        "dns_no_sync": false,
        "db_update_propagation": 0,
        "nginx_err_logs": "/usr/local/kong/logs/error.log",
        "cassandra_port": 9042,
        "dns_order": [
            "LAST",
            "SRV",
            "A",
            "CNAME"
        ],
        "dns_error_ttl": 1,
        "headers": [
            "server_tokens",
            "latency_tokens"
        ],
        "dns_stale_ttl": 4,
        "nginx_optimizations": true,
        "database": "postgres",
        "pg_database": "kong",
        "nginx_worker_processes": "auto",
        "lua_package_cpath": "",
        "admin_acc_logs": "/usr/local/kong/logs/admin_access.log",
        "lua_package_path": "./?.lua;./?/init.lua;",
        "nginx_pid": "/usr/local/kong/pids/nginx.pid",
        "upstream_keepalive": 60,
        "cassandra_contact_points": [
            "127.0.0.1"
        ],
        "client_ssl_cert_csr_default": "/usr/local/kong/ssl/kong-default.csr",
        "proxy_listeners": [
            {
                "ssl": false,
                "ip": "0.0.0.0",
                "proxy_protocol": false,
                "port": 8000,
                "http2": false,
                "listener": "0.0.0.0:8000"
            },
            {
                "ssl": true,
                "ip": "0.0.0.0",
                "proxy_protocol": false,
                "port": 8443,
                "http2": false,
                "listener": "0.0.0.0:8443 ssl"
            }
        ],
        "proxy_ssl_enabled": true,
        "admin_access_log": "logs/admin_access.log",
        "ssl_ciphers": "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256",
        "enabled_headers": {
            "latency_tokens": true,
            "X-Kong-Proxy-Latency": true,
            "Via": true,
            "server_tokens": true,
            "Server": true,
            "X-Kong-Upstream-Latency": true,
            "X-Kong-Upstream-Status": false
        },
        "cassandra_ssl": false,
        "ssl_cert_csr_default": "/usr/local/kong/ssl/kong-default.csr",
        "db_resurrect_ttl": 30,
        "client_max_body_size": "0",
        "cassandra_consistency": "ONE",
        "db_cache_ttl": 0,
        "admin_error_log": "logs/error.log",
        "pg_ssl_verify": false,
        "dns_not_found_ttl": 30,
        "pg_ssl": false,
        "client_ssl": false,
        "db_update_frequency": 5,
        "cassandra_repl_strategy": "SimpleStrategy",
        "nginx_kong_conf": "/usr/local/kong/nginx-kong.conf",
        "cassandra_repl_factor": 1,
        "nginx_http_directives": [
            {
                "value": "prometheus_metrics 5m",
                "name": "lua_shared_dict"
            }
        ],
        "error_default_type": "text/plain",
        "kong_env": "/usr/local/kong/.kong_env",
        "real_ip_header": "X-Real-IP",
        "dns_hostsfile": "/etc/hosts",
        "admin_listeners": [
            {
                "ssl": false,
                "ip": "0.0.0.0",
                "proxy_protocol": false,
                "port": 8001,
                "http2": false,
                "listener": "0.0.0.0:8001"
            },
            {
                "ssl": true,
                "ip": "0.0.0.0",
                "proxy_protocol": false,
                "port": 8444,
                "http2": false,
                "listener": "0.0.0.0:8444 ssl"
            }
        ],
        "admin_ssl_cert": "/usr/local/kong/ssl/admin-kong-default.crt",
        "ssl_cert": "/usr/local/kong/ssl/kong-default.crt",
        "proxy_access_log": "logs/access.log",
        "admin_ssl_cert_key_default": "/usr/local/kong/ssl/admin-kong-default.key",
        "cassandra_ssl_verify": false,
        "cassandra_lb_policy": "RoundRobin",
        "ssl_cipher_suite": "modern",
        "real_ip_recursive": "off",
        "proxy_error_log": "logs/error.log",
        "client_ssl_cert_key_default": "/usr/local/kong/ssl/kong-default.key",
        "nginx_daemon": "on",
        "anonymous_reports": true,
        "cassandra_timeout": 5000,
        "nginx_proxy_directives": {},
        "pg_port": 5432,
        "log_level": "notice",
        "client_body_buffer_size": "8k",
        "cassandra_schema_consensus_timeout": 10000,
        "lua_socket_pool_size": 30,
        "admin_ssl_cert_default": "/usr/local/kong/ssl/admin-kong-default.crt",
        "cassandra_keyspace": "kong",
        "ssl_cert_default": "/usr/local/kong/ssl/kong-default.crt",
        "nginx_conf": "/usr/local/kong/nginx.conf",
        "admin_listen": [
            "0.0.0.0:8001",
            "0.0.0.0:8444 ssl"
        ]
    },
    "version": "0.14.1",
    "node_id": "fee222ae-7871-49e5-a47c-bdc55410dc2a",
    "lua_version": "LuaJIT 2.1.0-beta3",
    "prng_seeds": {
        "pid: 2328": 177223337424,
        "pid: 2326": 145810617621,
        "pid: 2327": 712547711113,
        "pid: 2329": 114129841275
    },
    "timers": {
        "pending": 5,
        "running": 0
    },
    "hostname": "localhost.localdomain"
}

部分返回字段含义:

node_id : 正在运行的kong节点的uuid,当kong启动时随机生成,每次kong重启时这个uuid都会变

availabel_on_server : kong节点上安装的plugins的名称

enabled_in_cluster : kong节点中启用的插件,即在数据库中生成了对应存储表

2,查询节点状态

curl  http://localhost:8001/status
{
    "database": {
        "reachable": true
    },
    "server": {
        "connections_writing": 1,
        "total_requests": 67,
        "connections_handled": 46,
        "connections_accepted": 46,
        "connections_reading": 0,
        "connections_active": 2,
        "connections_waiting": 1
    }
}

**字段解释

字段 解释
total_requests 客户端请求总数
connections_active 包括等待连接的活动客户端连接的当前数量
connections_accepted 接受的客户端连接的总数
connections_handled 处理连接的总数。一般来说,除非达到一定的资源限制,否则参数值与接受值相同
connections_reading 当前Kong正在读取请求头的连接数
connections_writing NGINX将响应写入客户端的连接的当前数量
connections_waiting 等待请求的空闲客户端连接的当前数量
reachable 反映数据库连接状态的布尔值。注意,此标志不反映数据库本身的健康状况。

二,service服务

  kong v0.13.x官方建议用Service和Route模块来管理API,这样可以更好的管理,比如认证和策略统一配置。

1,Add Service(添加服务)

参数

字段 解释 备注
name 服务名称
protocol 协议:http or https 默认是 http 你后端服务用什么协议访问就写什么协议
host 后端服务域名
port 后端服务端口
path 后端服务子路径;没有就填 ‘/‘
retries 重试次数:默认 5次 默认就行
connect_timeout 请求后端服务的超时时间:默认60000 ms 1秒(s)=1000毫秒(ms)
write_timeout 写超时时间:默认60000 ms 1秒(s)=1000毫秒(ms)
read_timeout 读超时时间:默认60000 ms 1秒(s)=1000毫秒(ms)
url 后端服务url地址 一般就用这种方式,可以直接指定:protocol、host、port and path, 不用单独指定啦

使用

curl -i -X POST http://localhost:8001/services -d "name=test.service" -d "url=http://你的后端服务域名/api"

返回

{
    "host": "你的后端服务域名",
    "created_at": 1538093069,
    "connect_timeout": 60000,
    "id": "85c4d968-7b6f-48fc-b5b0-260cf8493821",
    "protocol": "http",
    "name": "test.service",
    "read_timeout": 60000,
    "port": 80,
    "path": "/api",
    "updated_at": 1538093069,
    "retries": 5,
    "write_timeout": 60000
}

注:url 这个属性很好用,可以直接指定 protocol、host、port and path。
**
也 可以这么写*

curl -i -X POST http://localhost:8001/services -d "name=test.service" -d "protocol=http" -d "host=hxonline.hxsd.cn" -d "path=/api"

2,Retrieve Service(查询服务)

查询所有服务

curl -i -X GET http://1localhost:8001/services

查询某个服务

curl -i -X GET http://localhost:8001/services/{服务名称 or 服务id}
EXP:
curl -i -X GET http://localhost:8001/services/test.service #我的服务名称

获取某个路由下的服务

curl -i -X GET http://localhost:8001/routes/{路由ID}/service 
EXP:
curl -i -X GET http://localhost:8001/routes/xxxx-xxx-xxx-xx/service

更新服务
可以用 PATCH 和 PUT,PATCH可以修改已存在的服务,PUT 如果服务不存在则新建一个。

curl -i -X PUT http://localhost:8001/services/{服务名称或ID} -d "name=test.service" -d "protocol=http" -d "host=hxonline.hxsd.cn" -d "path=/api"

删除服务

curl -i -X DELETE http://localhost:8001/services/{服务名称或ID}
EXP:
curl -i -X DELETE http://localhost:8001/services/test.service

返回

HTTP 204 No Content (看到这个就成功啦)

三、Route Object(路由)

路由是真正对外提供接口的实体,每个路由都与一个服务相关联,而服务可能有多个与之相关联的路由。每一个匹配给定路线的请求都将被提交给它的相关服务。

字段 解释 是否必填
protocols 协议列表,http、https。设置:protocols[]=http&protocols[]=https 必填
methods 接受请求的方法:GET 或 POST ,二者都行。设置 methods[]=GET&methods[]=POST 半选填:默认是二者都行
hosts 与此路由匹配的域名列表。例如:example.com。用作form-encode, 设置:hosts[]= Foo.com和hosts[]= BAR.com 半选填
paths 与此路由匹配的路径列表。例如:/test 必填:这个很重要,区分多服务
strip_path 选填
preserve_host 选填
service 与此路由绑定的服务。设置:service.id=<service_id> 必填

1,Add Route(添加路由)

curl -i -X POST --url  http://localhost:8001/routes/ \
  -d 'protocols[]=http&protocols[]=https' \
  -d 'paths=/test' \
  -d 'service.id=xxx-xxxx-xxxx-xx' #服务ID

访问接口

curl -i -X GET http://localhost:8000/test/{后端服务路由}
注:test 是创建路由是的 paths 字段。
EXP:
curl -i -X GET http://localhost:8000/test/userinfo

2,Retrieve Route (获取路由信息)

获取全部路由

curl -i -X GET http://localhost:8001/routes/

获取某个路由

curl -i -X GET http://localhost:8001/routes/xxx-xxx-xxx #路由ID

获取某服务下的路由

curl -i -X GET http://localhost:8001/services/{服务名或服务ID}/routes

更新路由
可以用 PATCH 和 PUT,PATCH可以修改已存在的路由,PUT 如果路由不存在则新建一个。

curl -i -X PUT http://localhost:8001/routes/xxx-xxx-xxx  \ #路由ID
    -d 'protocols[]=http&protocols[]=https' \
  -d 'paths=test' \

删除路由

curl -i -X DELETE   http://localhost:8001/routes/xxx-xxx-xxx   #路由ID

总结

到这里kong的服务和路由的设置已经完事了,接下来认证插件和acl的配合来保证对外接口的安全性。


ph.w
ph.w 9个月前

已被 1 人挖起

回应
登录 后发表评论
  • 消灭零回应