Version: 1.3.1.0

Référence Apache Knox

Apache Knox 2.1.0 est la passerelle périmétrique d'ODP. Il fournit un point d'entrée TLS unique pour tous les accès REST et interfaces web du cluster, éliminant le besoin d'exposer les ports individuels des services à l'extérieur.

Architecture de Knox

  Client externe (navigateur / curl / JDBC)
           │
           │ HTTPS :8443
           ▼
  ┌─────────────────────────┐
  │      Knox Gateway       │
  │                         │
  │  Topologie : default    │──► WebHDFS  :50070
  │  Topologie : cdp-proxy  │──► Hive JDBC :10000
  │  Topologie : admin      │──► Ambari    :8442
  └─────────────────────────┘
           │
    Authentification (LDAP / Kerberos)
    Autorisation (plugin Ranger Knox)
    Terminaison TLS

Knox fonctionne via des fichiers de topologie — des descripteurs XML qui définissent :

Quels services sont exposés via un chemin de passerelle donné.
Quel fournisseur d'authentification utiliser.
Les correspondances d'URL de service vers les hôtes/ports backend.

Chaque topologie est déployée comme un WAR dans la passerelle Knox et devient accessible à https://<hôte-knox>:8443/gateway/<nom-topologie>/.

Knox dans ODP (géré par Ambari)

Ambari gère automatiquement l'installation, la configuration et la génération de topologies Knox. Vous n'avez pas besoin d'écrire manuellement du XML de topologie pour les services standards.

Génération automatique de topologies par Ambari

Lorsque vous activez Knox dans Ambari et configurez les services à proxifier, Ambari génère les fichiers de topologie et les déploie vers Knox. La configuration se trouve sous Ambari → Services → Knox → Configs.

Paramètres Ambari Knox importants :

Paramètre	Description
`gateway.port`	Port HTTPS Knox (défaut : `8443`)
`knox.topology.name`	Nom de la topologie par défaut (`default`)
`gateway.hadoop.kerberos.secured`	Activer la gestion des tokens de délégation Kerberos
`knox.master.secret`	Secret maître Knox (chiffré dans le credential store Ambari)

Après modification de la configuration Knox dans Ambari, redémarrer le service Knox. Ambari régénère et redéploie automatiquement les fichiers de topologie.

Services derrière Knox

WebHDFS

Knox proxifie les appels REST WebHDFS vers le NameNode. Les clients s'authentifient auprès de Knox (LDAP ou Kerberos), et Knox utilise son propre keytab de service pour transférer les requêtes vers HDFS.

# Lister la racine HDFS via Knox
curl -iku user:password \
  "https://knox-host:8443/gateway/default/webhdfs/v1/?op=LISTSTATUS"

Hive JDBC (HiveServer2)

Knox proxifie les connexions JDBC Hive. Utiliser l'URL JDBC Knox dans Beeline :

beeline -u "jdbc:hive2://knox-host:8443/default;ssl=true;\
sslTrustStore=/chemin/truststore.jks;trustStorePassword=changeit;\
transportMode=http;httpPath=gateway/default/hive"

Interface YARN Resource Manager

https://knox-host:8443/gateway/default/yarn

Interface Ambari

Knox peut proxifier l'interface web Ambari, permettant l'accès administrateur via la passerelle Knox sans exposer le port 8442 d'Ambari :

https://knox-host:8443/gateway/admin/ambari

Autres services proxifiés

ODP expose typiquement via Knox :

Service	Chemin Knox
Interface NameNode HDFS	`/gateway/default/hdfs`
Historique MapReduce	`/gateway/default/jobhistory`
Interface HBase	`/gateway/default/hbase`
Oozie	`/gateway/default/oozie`
Zeppelin	`/gateway/default/zeppelin`
NiFi	`/gateway/default/nifi`

Authentification LDAP

Knox authentifie les utilisateurs auprès de LDAP (ou du LDAP intégré de FreeIPA) avant de transférer les requêtes aux services backend.

Ambari configure les paramètres LDAP sous Knox → Advanced gateway-site :

<!-- Extrait de topologie — Ambari génère ceci -->
<provider>
  <role>authentication</role>
  <name>ShiroProvider</name>
  <enabled>true</enabled>
  <param>
    <name>sessionTimeout</name>
    <value>30</value>
  </param>
  <param>
    <name>main.ldapRealm</name>
    <value>org.apache.hadoop.gateway.shirorealm.KnoxLdapRealm</value>
  </param>
  <param>
    <name>main.ldapRealm.userDnTemplate</name>
    <value>uid={0},cn=users,cn=accounts,dc=dev01,dc=hadoop,dc=clemlab,dc=com</value>
  </param>
  <param>
    <name>main.ldapRealm.contextFactory.url</name>
    <value>ldap://ipa01.dev01.hadoop.clemlab.com:389</value>
  </param>
</provider>

Configuration SSO

Knox SSO fournit une authentification unique basée sur le navigateur. Après qu'un utilisateur s'est authentifié une fois auprès de Knox, les requêtes suivantes vers d'autres services proxifiés par Knox réutilisent le token Knox sans redemander les identifiants.

Service de tokens Knox

Knox émet des JSON Web Tokens (JWT) signés après une authentification LDAP ou Kerberos réussie :

Le navigateur accède à https://knox-host:8443/gateway/knoxsso/api/v1/websso.
Knox redirige vers la page de connexion LDAP (ou effectue Kerberos SPNEGO).
En cas de succès, Knox émet un cookie JWT signé (hadoop-jwt).
Le navigateur présente le JWT à toutes les interfaces proxifiées par Knox automatiquement.

Activer Knox SSO dans Ambari sous Knox → Advanced topology en ajoutant le fournisseur federation avec JWTProvider.

Protection CSRF

Knox inclut une protection CSRF (Cross-Site Request Forgery) intégrée. Les clients basés sur navigateur doivent inclure un en-tête HTTP personnalisé :

X-Requested-By: Knox

La plupart des clients Hadoop (Beeline, CLI HDFS via Knox) ajoutent cet en-tête automatiquement. Pour les clients REST personnalisés, ajouter l'en-tête explicitement :

curl -iku user:password \
  -H "X-Requested-By: Knox" \
  -X PUT \
  "https://knox-host:8443/gateway/default/webhdfs/v1/user/test?op=MKDIRS"

Configuration TLS/SSL

Knox termine TLS pour toutes les connexions entrantes. Dans ODP, la fonctionnalité Auto-TLS d'Ambari génère et distribue automatiquement les certificats pour Knox.

Configuration manuelle des certificats

Si Auto-TLS n'est pas utilisé, placer le keystore de la passerelle Knox à :

/usr/odp/current/knox-server/data/security/keystores/gateway.jks

Configurer le keystore dans gateway-site.xml :

<property>
  <name>ssl.exclude.protocols</name>
  <value>SSLv3,TLSv1,TLSv1.1</value>
</property>
<property>
  <name>gateway.tls.keystore.path</name>
  <value>/usr/odp/current/knox-server/data/security/keystores/gateway.jks</value>
</property>

Confiance côté client

Les clients se connectant à Knox doivent faire confiance au certificat Knox. Distribuer le certificat CA ou le certificat auto-signé de la passerelle aux clients :

# Importer le certificat Knox dans le truststore Java
keytool -import -alias knox-gateway \
  -file /chemin/vers/knox.crt \
  -keystore /etc/pki/ca-trust/extracted/java/cacerts \
  -storepass changeit -noprompt

Référence des ports

Port	Protocole	Objectif
8443	HTTPS	Passerelle Knox — tout le proxying de services et Knox SSO
8444	HTTPS	API Admin Knox (CRUD de topologies, gestion des services)

L'API Admin Knox sur le port 8444 permet le déploiement programmatique de topologies :

# Lister les topologies déployées
curl -iku admin:admin-password \
  "https://knox-host:8444/gateway/admin/api/v1/topologies"

Structure d'un fichier de topologie (référence)

Ambari génère les fichiers de topologie automatiquement, mais comprendre leur structure aide lors du dépannage.

<topology>
  <gateway>
    <provider>
      <role>authentication</role>
      <name>ShiroProvider</name>
      <enabled>true</enabled>
      <!-- Paramètres LDAP -->
    </provider>
    <provider>
      <role>authorization</role>
      <name>XASecurePDPKnox</name>
      <enabled>true</enabled>
    </provider>
    <provider>
      <role>identity-assertion</role>
      <name>Default</name>
      <enabled>true</enabled>
    </provider>
    <provider>
      <role>ha</role>
      <name>HaProvider</name>
      <enabled>true</enabled>
      <param><name>WEBHDFS</name><value>maxFailoverAttempts=3;failoverSleep=1000;maxRetryAttempts=300;retrySleep=1000;enabled=true</value></param>
    </provider>
  </gateway>

  <service>
    <role>WEBHDFS</role>
    <url>http://master01.dev01.hadoop.clemlab.com:50070/webhdfs</url>
    <url>http://master02.dev01.hadoop.clemlab.com:50070/webhdfs</url>
  </service>

  <service>
    <role>HIVE</role>
    <url>http://master02.dev01.hadoop.clemlab.com:10001/cliservice</url>
    <url>http://master03.dev01.hadoop.clemlab.com:10001/cliservice</url>
  </service>
</topology>

Les fichiers de topologie sont stockés à :

/usr/odp/current/knox-server/conf/topologies/<nom-topologie>.xml

Ambari écrit dans ce chemin lors des redémarrages de Knox. Ne pas modifier ces fichiers manuellement — utiliser Ambari pour s'assurer que les modifications survivent aux redémarrages de service.

Référence Apache Knox

Architecture de Knox​

Knox dans ODP (géré par Ambari)​

Génération automatique de topologies par Ambari​

Services derrière Knox​

WebHDFS​

Hive JDBC (HiveServer2)​

Interface YARN Resource Manager​

Interface Ambari​

Autres services proxifiés​

Authentification LDAP​

Configuration SSO​

Service de tokens Knox​

Protection CSRF​

Configuration TLS/SSL​

Configuration manuelle des certificats​

Confiance côté client​

Référence des ports​

Structure d'un fichier de topologie (référence)​