NGINX Ingress Controllerの柔軟なアプリケーション制御、具体的なユースケースと設定方法を理解する

【補足】

事象の切り分け方法

各パートでKubernetes環境にデプロイしたアプリケーションの動作が期待した通りとならない場合の切り分けについてご紹介します。

1. 各リソースのデプロイに失敗する
   ・「kubectl describe <resource type> <resource name> (-n <namespace>)」コマンドの結果を確認し、リソースのデプロイでエラーが発生していないか確認してください
   ・「kubectl logs <pod name> (-n <namespace>)」コマンドの結果を確認し、PODのログメッセージを確認し、エラーが発生していないか確認してください
2. リソースは正しく作成できたが設定が反映されない
   ・1.の内容を参考にコマンドを実行してください
   ・特にリソースが正しく生成された場合でも、NGINXのコンフィグロードでエラーとなる場合があります。その場合には、「kubectl logs」コマンドでコンフィグロードに失敗する理由が表示されておりますのでそちらでご確認ください
   ・一度設定の反映に成功し、その後リソースの内容変更によりエラーが発生した場合には、リソースの変更前の設定で動作いたします。注意深くログを確認し、問題箇所を特定してください
3. 期待した疎通ができない
   ・「kubectl logs <NGINX Ingress Controller pod> -n nginx-ingress」コマンドの結果を確認し、Access LogとError Logの内容を確認してください
   ・NGINX Ingress Controllerで通信を受け付けた場合には以下のようにログが出力されます。ログが出力されること、ログの内容をもとに期待した通信となっているか確認してください
   

   10.244.0.1 - - [24/Aug/2021:14:30:51 +0000] "GET / HTTP/1.1" 500 178 "-" "curl/7.68.0" "-"
   10.244.0.1 - - [25/Aug/2021:05:47:17 +0000] "POST / HTTP/1.1" 200 246 "-" "curl/7.68.0" "-"
   10.244.0.1 - - [25/Aug/2021:05:47:09 +0000] "POST / HTTP/1.1" 200 246 "-" "curl/7.68.0" "-"

4. 設定の内容を確認したい
   ・NGINX Ingress Controllerは本書で紹介のVirtualServer / VirtualServerRoute / PolicyやIngressにより設定を行うと、それらの内容からNGINXの設定ファイルに変換し、その内容を反映しています
   ・「kubectl exec -it <NGINX Ingress Controller pod> -n nginx-ingress」 -- bash」コマンドを実行し、NGINX Ingress ControllerのShellを操作することが可能です
   ・以下フォルダの各ファイルが適切な設定となっているかご確認ください。意図したファイルが生成されていない場合にはリソースの作成に失敗している可能性がありますのでログをご確認ください。
   

   /etc/nginx/conf.d/	HTTP/HTTPSの主な設定が格納されます。複数のVirtualServerをデプロイした場合には複数のファイルが生成されます。 ■生成されるファイル名 vs_<namespace>_<object name>.conf
   /etc/nginx/stream-conf.d/	TCP/UDPの主な設定が格納されます。複数のTransportServerをデプロイした場合には複数のファイルが生成されます。合わせて必要となるGlobalConfigurationの作成も完了していることを確認してください。 ■生成されるファイル名 ts_<namespace>_<object name>.conf
   /etc/nginx/secrets/	証明書・鍵のファイルが格納されます。複数のSecretをデプロイした場合には複数のファイルが生成されます。参照先のオブジェクトの生成が成功した際に、本ファイルが生成されます。 ■生成されるファイル名 <namespace>-<object name>
   /etc/nginx/waf/nac-policies/	WAFのセキュリティポリシーが格納されます。複数のAPPolicyをデプロイした場合には複数のファイルが生成されます。 ■生成されるファイル名 <namespace>_<object name>
   /etc/nginx/waf/nac-logconfs/	WAFのログポリシーが格納されます。複数のAPLogConfをデプロイした場合には複数のファイルが生成されます。ログポリシーの参照先となるWAFセキュリティポリシーの生成が成功した際に、本ファイルが生成されます。 ■生成されるファイル名 <namespace>_<object name>
   /etc/nginx/waf/nac-usersigs/	WAFのユーザ定義Signatureが格納されます。複数のAPUserSigをデプロイした場合には複数のファイルが生成されます。ログポリシーの参照先となるWAFセキュリティポリシーの生成が成功した際に、本ファイルが生成されます。 ■生成されるファイル名 <namespace>_<object name>
   /etc/nginx/oidc/	OIDCで参照するファイルが格納されています。

OIDC KeycloakのAPI操作について

OIDCで利用するKeycloakですがGUIを利用せずAPIで設定することが可能です。KeyacloakのAPIを利用した設定方法はGitHub上のKeycloak Setupに記載されています。

APIではJSON形式のデータをやり取りします。予めjqコマンドをインストールしてください。

まずKeycloakにアクセスするため、クライアント端末のhostsファイルで適切にアクセスできるよう設定してください。

# grep host virtual-server-idp.yaml
virtual-server-idp.yaml:  host: keycloak.example.com

APIより操作するためAccess Tokenを取得します。Access Tokenの有効期限は大変短く設定されております(60秒)。ご注意ください。

APIで利用するAccess Tokenの取得
# TOKEN=`curl -sS -k --data "username=admin&password=admin&grant_type=password&client_id=admin-cli" https://keycloak.example.com/auth/realms/master/protocol/openid-connect/token | jq -r .access_token`

nginx-userというユーザ名を持つユーザの作成
# curl -sS -k -X POST -d '{ "username": "nginx-user", "enabled": true, "credentials":[{"type": "password", "value": "test", "temporary": false}]}' -H "Content-Type:application/json" -H "Authorization: bearer ${TOKEN}" https://keycloak.example.com/auth/admin/realms/master/users

nginx-userの設定追加及びSECRETの取得
# SECRET=`curl -sS -k -X POST -d '{ "clientId": "nginx-plus", "redirectUris": ["https://webapp.example.com/_codexch"] }' -H "Content-Type:application/json" -H "Authorization: bearer ${TOKEN}" https://keycloak.example.com/auth/realms/master/clients-registrations/default | jq -r .secret`

取得したSECRETの確認
# echo $SECRET
***SECRET***

Keycloakの設定作業で正しく値が取得できない場合、以下コマンドを参考に切り分けを行い、適切にSECRETの取得が完了することを確認してください。

指定の管理者ユーザ名、パスワードを用いて正しくTokenが取得できることを確認してください。APIではこちらのAccessTokenを利用します。
# curl -sS -k --data "username=admin&password=admin&grant_type=password&client_id=admin-cli" https://keycloak.example.com/auth/realms/master/protocol/openid-connect/token | jq .
{
  "access_token": "***ACCESS TOKEN***",
  "expires_in": 60,
  "refresh_expires_in": 1800,
  "refresh_token": "***REFRESH TOKEN***",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "f1cc69a8-2239-424a-9e48-f73ab29ef931",
  "scope": "profile email"
}

ユーザ情報を取得。管理者及び新規に作成する「nginx-plus」というユーザが表示されることを確認してください
# curl -sS -k -H "Content-Type:application/json" -H "Authorization: bearer ${TOKEN}" https://keycloak.example.com/auth/admin/realms/master/users | jq .
[
  {
    "id": "3d0cf453-5d72-494f-9e8f-f3c3aa8e279b",
    "createdTimestamp": 1629247264332,
    "username": "admin",
    "enabled": true,
    "totp": false,
    "emailVerified": false,
    "disableableCredentialTypes": [],
    "requiredActions": [],
    "notBefore": 0,
    "access": {
      "manageGroupMembership": true,
      "view": true,
      "mapRoles": true,
      "impersonate": true,
      "manage": true
    }
  },
  {
    "id": "4fd6d403-db91-4d84-9235-84a418a5b8ef",
    "createdTimestamp": 1629704326796,
    "username": "nginx-user",
    "enabled": true,
    "totp": false,
    "emailVerified": false,
    "disableableCredentialTypes": [],
    "requiredActions": [],
    "notBefore": 0,
    "access": {
      "manageGroupMembership": true,
      "view": true,
      "mapRoles": true,
      "impersonate": true,
      "manage": true
    }
  }
]

登録されたクライアント情報を確認し、必要となる情報を確認してください。NGINX OIDCの設定で規定した動作とならない場合にはこちらに表示されるパラメータを参照し、確認を行ってください。
# curl -sS -k -X GET -H "Content-Type:application/json" -H "Authorization: bearer ${TOKEN}" https://keycloak.example.com/auth/realms/master/clients-registrations/default/nginx-plus | jq .
{
  "id": "32f41851-f0f7-4259-af19-68e11b5bb10c",
  "clientId": "nginx-plus",
  "surrogateAuthRequired": false,
  "enabled": true,
  "alwaysDisplayInConsole": false,
  "clientAuthenticatorType": "client-secret",
  "secret": "***SECRET***",
  "redirectUris": [
    "https://webapp.example.com:443/_codexch"
  ],
  "webOrigins": [
    "https://webapp.example.com:443"
  ],
  "notBefore": 0,
  "bearerOnly": false,
  "consentRequired": false,
  "standardFlowEnabled": true,
  "implicitFlowEnabled": false,
  "directAccessGrantsEnabled": false,
  "serviceAccountsEnabled": false,
  "publicClient": false,
  "frontchannelLogout": false,
  "protocol": "openid-connect",
  "attributes": {},
  "authenticationFlowBindingOverrides": {},
  "fullScopeAllowed": true,
  "nodeReRegistrationTimeout": -1,
  "defaultClientScopes": [
    "web-origins",
    "role_list",
    "profile",
    "roles",
    "email"
  ],
  "optionalClientScopes": [
    "address",
    "phone",
    "offline_access",
    "microprofile-jwt"
  ]
}

Keycloakで誤った情報、意図しない情報でオブジェクトを作成した場合には以下コマンドを参考に削除してください。

・ユーザの削除
# curl -sS -k -X DELETE -H "Content-Type:application/json" -H "Authorization: bearer ${TOKEN}" https://keycloak.example.com/auth/admin/realms/master/users/ | jq .

・クライアントの削除
# curl -sS -k -X DELETE -H "Content-Type:application/json" -H "Authorization: bearer ${TOKEN}" https://keycloak.example.com/auth/realms/master/clients-registrations/default/ | jq .