4장. APIcast 정책

다음 예는 정책 체인 구성을 보여줍니다.

"policy_chain": [
    {
      "name": "apicast.policy.apicast"
    },
    {
      "name": "apicast.policy.camel",
      "configuration": {
          "all_proxy": "http://192.168.15.103:8080/",
          "http_proxy": "http://192.168.15.103:8080/",
          "https_proxy": "http://192.168.15.103:8443/"
      }
    }
]

http _proxy 또는 https_proxy 가 정의되지 않은 경우 all _proxy 값이 사용됩니다.

조건 정책 체인에서 정책을 실행할지 여부를 결정하는 조건은 JSON 을 사용하여 표현할 수 있으며 유동 템플릿을 사용합니다.

이 예제에서는 요청 경로가 /example_path:

{
  "left": "{{ uri }}",
  "left_type": "liquid",
  "op": "==",
  "right": "/example_path",
  "right_type": "plain"
}

왼쪽 및 오른쪽 피연산자는 모두 유동 또는 일반 문자열로 평가할 수 있습니다. 일반 문자열이 기본값입니다.

작업을 및 또는 와 결합할 수 있습니다. 이 구성은 이전 예와 백엔드 헤더의 값과 동일하게 확인합니다.

{
  "operations": [
    {
      "left": "{{ uri }}",
      "left_type": "liquid",
      "op": "==",
      "right": "/example_path",
      "right_type": "plain"
    },
    {
      "left": "{{ headers['Backend'] }}",
      "left_type": "liquid",
      "op": "==",
      "right": "test_upstream",
      "right_type": "plain"
    }
  ],
  "combine_op": "and"
}

자세한 내용은 정책 구성 스키마 를 참조하십시오.

{
   "name":"conditional",
   "version":"builtin",
   "configuration":{
      "condition":{
         "operations":[
            {
               "left":"{{ headers['Backend'] }}",
               "left_type":"liquid",
               "op":"==",
               "right":"staging"
            }
         ]
      },
      "policy_chain":[
         {
            "name":"upstream",
            "version": "builtin",
            "configuration":{
               "rules":[
                  {
                     "regex":"/",
                     "url":"http://my_staging_environment"
                  }
               ]
            }
         }
      ]
   }
}

NGINX proxy_cache_valid 지시문 정보는 APICAST_CACHE_ STATUS_CODES 및 APICAST_CACHE_ MAX_TIME 을 사용하여 전역적으로 설정할 수 있습니다. 업스트림에 시간 초과와 관련된 다른 동작이 필요한 경우 Cache-Control 헤더를 사용합니다.

다음 차트는 인증이 캐시되지 않은 경우의 요청 흐름 및 인증이 캐시될 때의 흐름도 보여줍니다.

이 정책은 업스트림 API에서 400 상태를 반환하는 경우 헤더 증가로 메트릭 오류를 늘립니다.

{
  "name": "apicast.policy.custom_metrics",
  "configuration": {
    "rules": [
      {
        "metric": "error",
        "increment": "{{ resp.headers['increment'] }}",
        "condition": {
          "operations": [
            {
              "right": "{{status}}",
              "right_type": "liquid",
              "left": "400",
              "op": "=="
            }
          ],
          "combine_op": "and"
        }
      }
    ]
  }
}

이 정책은 업스트림 API에서 200 상태를 반환하는 경우 status_code 정보를 사용하여 hits 메트릭을 늘립니다.

{
  "name": "apicast.policy.custom_metrics",
  "configuration": {
    "rules": [
      {
        "metric": "hits_{{status}}",
        "increment": "1",
        "condition": {
          "operations": [
            {
              "right": "{{status}}",
              "right_type": "liquid",
              "left": "200",
              "op": "=="
            }
          ],
          "combine_op": "and"
        }
      }
    ]
  }
}

정책은 lua-resty-limit-traffic 라이브러리에서 제공하는 다음 유형의 제한을 지원합니다.

서비스 또는 전역적으로 제한 범위를 지정할 수 있습니다.

제한에는 IP 주소, 서비스, 엔드포인트, 식별자, 특정 헤더의 값 및 기타 엔터티와 같이 제한을 정의하는 데 사용되는 엔터티를 인코딩하는 키가 있습니다. 이 키는 limiter의 key 매개변수에 지정됩니다.

key 는 다음 속성으로 정의된 오브젝트입니다.

각 제한에는 유형에 따라 몇 가지 매개변수도 있습니다.

각 서비스에 대해 여러 제한을 정의할 수 있습니다. 여러 제한이 정의되는 경우 한 개 이상의 제한에 도달하면 요청이 거부되거나 지연될 수 있습니다.

에지 제한 정책을 사용하면 키에 있는 변수를 지원하여 동적 키에 대한 제한을 지정할 수 있습니다. 이를 위해 키의 name_type 매개 변수를ude로 설정해야 하며 name 매개 변수에서 변수를 사용할 수 있습니다. 예를 들어, {{ remote_addr }} (클라이언트 IP 주소의 경우 {{ jwt.sub }} ) 또는 JWT 토큰의 하위 클레임의 경우 {{ jwt.sub }}입니다.

{
  "key": { "name": "{{ jwt.sub }}", "name_type": "liquid" },
  "count": 10,
  "window": 60
}

ms 지원에 대한 자세한 내용은 5.1절. “정책에서 변수 및 필터 사용” 의 내용을 참조하십시오.

각 제한 프로그램에는 제한이 적용되는 시기를 정의하는 조건이 있어야 합니다. 조건은 제한자의 condition 속성에 지정됩니다.

조건은 다음 속성에 의해 정의됩니다.

"condition": {
  "combine_op": "and",
  "operations": [
    {
      "op": "==",
      "right": "GET",
      "left_type": "liquid",
      "left": "{{ http_method }}",
      "right_type": "plain"
    }
  ]
}

기본적으로 에지 제한 정책은 속도 제한 카운터에 OpenResty 공유 사전을 사용합니다. 그러나 공유 사전 대신 외부 Redis 서버를 사용할 수 있습니다. 이 기능은 여러 APIcast 인스턴스가 배포될 때 유용할 수 있습니다. redis_url 매개 변수를 사용하여 Redis 서버를 구성할 수 있습니다.

제한자는 오류를 처리하는 방법을 구성하기 위해 다음 매개변수를 지원합니다.

JWT 클레임의 값을 기반으로 라우팅하려면 JWT를 검증하고 정책이 공유하는 컨텍스트에 클레임을 저장하는 체인에 정책이 필요합니다.

JWT Claim Check 정책이 리소스와 방법을 차단하는 경우 정책은 JWT 작업도 검증합니다. 또는 메서드 리소스가 일치하지 않는 경우 요청은 백엔드 API로 계속됩니다.

예제: GET 요청의 경우 요청이 거부되지 않는 경우 JWT에 역할 클레임이 admin으로 있어야 합니다. 반면 GET 이외의 요청은 JWT 작업을 검증하지 않으므로 JWT 제약 조건 없이 POST 리소스가 허용됩니다.

{
  "name": "apicast.policy.jwt_claim_check",
  "configuration": {
      "error_message": "Invalid JWT check",
      "rules": [
          {
              "operations": [
                  {"op": "==", "jwt_claim": "role", "jwt_claim_type": "plain", "value": "admin"}
              ],
              "combine_op":"and",
              "methods": ["GET"],
              "resource": "/resource",
              "resource_type": "plain"
          }
      ]
  }
}

정책 체인에서 JWT Claim Check 정책을 구성하려면 다음을 수행합니다.

로깅 옵션은 API에서 올바르게 포맷되지 않은 로그 문제를 방지하는 데 도움이 됩니다. 사용자 지정 APIcast 환경 변수를 설정하고 모든 API에서 로깅 정책을 구현합니다. 다음은 모든 서비스에 로드된 정책의 예입니다. custom_env.lua

local cjson = require('cjson')
local PolicyChain = require('apicast.policy_chain')
local policy_chain = context.policy_chain

local logging_policy_config = cjson.decode([[
{
  "enable_access_logs": false,
  "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}"
}
]])

policy_chain:insert( PolicyChain.load_policy('logging', 'builtin', logging_policy_config), 1)

return {
  policy_chain = policy_chain,
  port = { metrics = 9421 },
}

이 특정 환경에서 APIcast를 실행하려면 다음을 수행합니다.

docker run --name apicast --rm -p 8080:8080 \
    -v $(pwd):/config \
    -e APICAST_ENVIRONMENT=/config/custom_env.lua \
    -e THREESCALE_PORTAL_ENDPOINT=https://ACCESS_TOKEN@ADMIN_PORTAL_DOMAIN \
    quay.io/3scale/apicast:master

다음은 고려해야 할 Docker 명령의 주요 개념입니다.

이 섹션에서는 로깅 정책 작업 시 몇 가지 예를 설명합니다. 다음 예제에서는 다음 주의 사항을 고려합니다.

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "[{{time_local}}] {{host}}:{{server_port}} {{remote_addr}}:{{remote_port}} \"{{request}}\" {{status}} {{body_bytes_sent}} ({{request_time}}) {{post_action_impact}}",
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}",
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "enable_json_logs": true,
    "json_object_config": [
      {
        "key": "host",
        "value": "{{host}}",
        "value_type": "liquid"
      },
      {
        "key": "time",
        "value": "{{time_local}}",
        "value_type": "liquid"
      },
      {
        "key": "custom",
        "value": "custom_method",
        "value_type": "plain"
      }
    ]
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}",
    "condition": {
      "operations": [
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "200"}
      ],
      "combine_op": "and"
    }
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}",
    "condition": {
      "operations": [
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "200"},
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "500"}
      ],
      "combine_op": "or"
    }
  }
}

사용자 정의 로깅의 경우 내보낸 변수와 함께 템플릿을 사용할 수 있습니다. 이러한 변수는 다음과 같습니다.

다음 예는 정책 체인 구성을 보여줍니다.

"policy_chain": [
    {
      "name": "apicast.policy.apicast"
    },
    {
      "name": "apicast.policy.http_proxy",
      "configuration": {
          "all_proxy": "http://192.168.15.103:8888/",
          "https_proxy": "https://192.168.15.103:8888/",
          "http_proxy": "https://192.168.15.103:8888/"
      }
    }
]

http _proxy 또는 https_proxy 가 정의되지 않은 경우 all _proxy 값이 사용됩니다.

다음 RateLimit 헤더는 각 메시지에 추가됩니다.

기본적으로 Rate Limit Headers 정책이 구성되지 않거나 애플리케이션 계획에 속도 제한이 없는 경우 응답 메시지에는 속도 제한 헤더가 없습니다.

경로가 /accounts 일 때 http://example.com 로 라우팅하는 구성입니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              }
            ]
          }
        }
      ]
    }
  }

Test-Header 헤더 값이 123 일 때 http://example.com 로 라우팅하는 구성입니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

쿼리 인수 test_query_arg 의 값이 123 일 때 http://example.com 로 라우팅하는 구성입니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "query_arg",
                "query_arg_name": "test_query_arg",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

JWT 클레임의 값을 기반으로 라우팅하려면 JWT를 검증하고 정책이 공유하는 컨텍스트에 저장하는 체인에 정책이 있어야 합니다.

JWT 클레임 test_claim 값이 123 일 때 http://example.com 로 라우팅하는 구성입니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "jwt_claim",
                "jwt_claim_name": "test_claim",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

규칙은 모두 '및' combine_op를 사용하여 또는 하나 이상의 값이 true(또는' combine_op사용)로 평가되는 경우에만 지정된 업스트림에 대한 여러 개의 작업과 경로를 가질 수 있습니다. combine_op 의 기본값은 '및'입니다.

요청 경로가 /accounts 이고 헤더 Test-Header 값이 123 인 경우 http://example.com 로 라우팅하는 구성입니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "combine_op": "and",
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              },
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

요청 경로가 /accounts 이거나 헤더 Test-Header 값이 123 인 경우 http://example.com 로 라우팅하는 구성입니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "combine_op": "or",
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              },
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

룰을 결합할 수 있습니다. 여러 규칙이 있는 경우 선택한 업스트림 규칙은 true로 평가되는 첫 번째 규칙 중 하나입니다.

몇 가지 규칙이 있는 구성입니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://some_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              }
            ]
          }
        },
        {
          "url": "http://another_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/users"
              }
            ]
          }
        }
      ]
    }
  }

작업이 없는 규칙은 항상 일치합니다. 범용 규칙을 정의하는 데 유용할 수 있습니다.

이 구성은 요청을 http://some_upstream.com 로 라우팅하고 경로가 /abc 인 경우 http://another_upstream.com 로 요청을 라우팅하고, 마지막으로 요청을 http://another_upstream.com로 라우팅하고 , 이전 규칙이 true로 평가되지 않은 경우 http://default_upstream.com 로 라우팅합니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://some_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/abc"
              }
            ]
          }
        },
        {
          "url": "http://another_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/def"
              }
            ]
          }
        },
        {
          "url": "http://default_upstream.com",
          "condition": {
            "operations": []
          }
        }
      ]
    }
  }

지원되는 작업은 ==, !=, 일치 항목입니다. 후자는 정규 표현식이 있는 문자열과 일치하며 ngx.re.match를 사용하여 구현됩니다.

이는 != 을 사용하는 구성입니다. 경로가 /accounts 가 아닌 경우 http://example.com 로 라우팅됩니다 :

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "!=",
                "value": "/accounts"
              }
            ]
          }
        }
      ]
    }
  }

구성 값에 유동 템플릿을 사용할 수 있습니다. 이를 통해 체인에 있는 정책이 컨텍스트에 my_var 키를 저장하는 경우 동적 값으로 규칙을 정의할 수 있습니다.

이 구성은 해당 값을 사용하여 요청을 라우팅하는 구성입니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "{{ my_var }}",
                "value_type": "liquid"
              }
            ]
          }
        }
      ]
    }
  }

기본적으로 요청이 라우팅되면 정책은 일치하는 규칙의 URL 호스트를 사용하여 Host 헤더를 설정합니다. host _header 특성을 사용하여 다른 호스트 를 지정할 수 있습니다.

이 구성은 some_host.com 을 호스트 헤더의 호스트로 지정하는 구성입니다.

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "host_header": "some_host.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/"
              }
            ]
          }
        }
      ]
    }
  }

TLS를 종료하도록 APIcast를 구성해야 합니다. 아래 단계에 따라 클라이언트 인증서 유효성 검사 정책을 사용하여 APIcast에서 사용자가 제공한 클라이언트 인증서의 유효성 검사를 구성합니다.

정책 체인에서 TLS 클라이언트 인증서 유효성 검사를 구성하려면 다음을 수행합니다.

TLS 클라이언트 인증서 유효성 검사 정책의 기능을 확인하려면 다음을 수행합니다.

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/client.crt --key ca/keys/client.key

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/server.crt --key ca/keys/server.key

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt

허용 목록에서 인증서를 제거하려면 다음을 수행합니다.

인증서 사용에 대한 자세한 내용은 Red Hat Certificate System 을 참조하십시오.

이 섹션에서는 PEM(개인 정보 보호 강화 메일) 형식 인증서를 사용하여 정책 체인에서 TLS 종료를 구성하는 전제 조건 및 단계에 대해 설명합니다.

이 섹션에서는 TLS 종료 정책에서 인증서 및 키 파일을 제거하는 단계를 설명합니다.

이 섹션에서는 정책 체인에서 업스트림 연결 정책을 구성하는 단계에 대해 설명합니다.

이 섹션에서는 정책 체인에서 업스트림 상호 TLS 정책을 구성하는 단계를 설명합니다.

변경 사항을 승격하려면 다음을 수행합니다.

다음은 명령 목록 의 각 명령이 구성된 구성 매개변수입니다.

다음은 query_args_commands 목록의 각 명령이 구성된 구성 매개변수입니다.

예제

URL 재작성 정책은 다음과 같이 구성됩니다.

{
  "name": "url_rewriting",
  "version": "builtin",
  "configuration": {
    "query_args_commands": [
      {
        "op": "add",
        "arg": "addarg",
        "value_type": "plain",
        "value": "addvalue"
      },
      {
        "op": "delete",
        "arg": "user_key",
        "value_type": "plain",
        "value": "any"
      },
      {
        "op": "push",
        "arg": "pusharg",
        "value_type": "plain",
        "value": "pushvalue"
      },
      {
        "op": "set",
        "arg": "setarg",
        "value_type": "plain",
        "value": "setvalue"
      }
    ],
    "commands": [
      {
        "op": "sub",
        "regex": "^/api/v\\d+/",
        "replace": "/internal/",
        "options": "i"
      }
    ]
  }

APIcast로 전송된 원래 요청 URI:

https://api.example.com/api/v1/products/123/details?user_key=abc123secret&pusharg=first&setarg=original

URL 다시 작성을 적용한 후 APIcast가 API 백엔드로 전송하는 URI입니다.

https://api-backend.example.com/internal/products/123/details?pusharg=first&pusharg=pushvalue&setarg=setvalue

다음과 같은 변환이 적용됩니다.

정책을 구성하는 방법에 대한 자세한 내용은 문서의 3scale 섹션의 정책 체인 만들기 섹션을 참조하십시오.