WebHDFS (Knox)

Le backend webhdfs lit HDFS, en lecture seule, a travers WebHDFS d’Apache Knox : HTTPS, un compte de service en Basic, au nom de l’utilisateur (doAs). Knox porte Kerberos vers le cluster. Sert aussi un HttpFS ou un WebHDFS sans Kerberos ; Hadoop 2.8 et plus.

[[backends]]
name = "datalake"
type = "webhdfs"
url = "https://knox.example.com:8443/gateway/default"
auth = { type = "basic", username = "svc-sftp", password_file = "/run/secrets/knox-password" }
ca_bundle = "/etc/craft-file-gate/knox-ca.pem"   # la CA privee de Knox

[[roles]]
name = "analystes"

[[roles.mounts]]
backend = "datalake"
mount_path = "/datalake"
home_dir = "/data/projets"
acl = [{ path = "/", rights = ["read", "list"], recursive = true }]

alice lit /datalake/2026/x.csv : la requete vise <url>/webhdfs/v1/data/projets/2026/x.csv?op=OPEN&doAs=alice.

Les cles

Toutes les cles : Reference [[backends]] type = “webhdfs”.

La connexion a Knox s’ouvre en 5 s au plus ; HTTPS_PROXY n’est pas suivie. Cles communes : Les backends.

Le montage sur WebHDFS

Cle	Sur WebHDFS
`home_dir` (montage)	un repertoire HDFS ; `.` et `..` ne sont jamais resolus
`create_home` (montage)	sans effet
`acl` (montage)	`read` et `list` : le reste n’a pas d’effet

Avec doAs, le nom d’utilisateur est fait de A-Z a-z 0-9 . _ -, 64 caracteres au plus.

hidden_stores, refuse_upload_over_directory, stale_partials, cross_instance_reservation et lock_prefix sont sans objet : rien n’est ecrit. case_insensitive : laissez-la absente, HDFS compare octet a octet.

Prerequis

Le droit de nommer un utilisateur (doAs), avec impersonate = true. Qui le donne depend de ce qui est derriere url :

Derriere `url`	Le reglage
Knox (le cas vise)	cote Knox : dans la topologie, l’assertion d’identite avec l’impersonation active et `hadoop.proxyuser.svc-sftp.users`, `.groups`, `.hosts` ; la topologie expose `WEBHDFS` et authentifie `svc-sftp` en Basic (`ShiroProvider` sur LDAP/AD). Cote cluster, `hadoop.proxyuser.knox.*`, pose en general par l’installation de Knox
WebHDFS en direct	`svc-sftp` declare mandataire dans `core-site.xml` (ci-dessous)
HttpFS	les memes droits, sous `httpfs.proxyuser.svc-sftp.` dans `httpfs-site.xml`

<property>
  <name>hadoop.proxyuser.svc-sftp.hosts</name>
  <value>sftp-gateway.example.com</value>  <!-- d'ou il se presente -->
</property>
<property>
  <name>hadoop.proxyuser.svc-sftp.groups</name>
  <value>sftp-users</value>                <!-- pour qui il agit -->
</property>

Au demarrage, le serveur fait un GETFILESTATUS de la racine HDFS sous le compte de service, sans doAs, 5 s au plus.

Ce que fait le backend

Operation	Requete WebHDFS
`stat`, existence d’un parent	`GETFILESTATUS`, une requete par chemin
listage	`LISTSTATUS_BATCH`, page par page (`startAfter`) ; `LISTSTATUS` en une reponse sur un cluster plus ancien que 2.8
telechargement, reprise, lecture a un offset	`OPEN?offset=&length=`, par plages
envoi, `mkdir`, renommage, suppression	aucune : lecture seule

Lecture anticipee : 10 Mio lus par paquets SFTP de 32 Kio coutent 3 OPEN avec le defaut ; une lecture qui saute ne demande que sa taille.
Listages : lus jusqu’au bout, plafonnes a 10 000 pages, 1 000 000 d’entrees et 64 Mio par reponse.
Redirections : un 307 de Knox est suivi une fois, vers la meme origine (schema, hote, port) que url seulement.
Une entree SYMLINK est montree comme un lien, et ne se lit pas ; HDFS compare les noms octet a octet, l’ACL aussi.

Performances et limites

Knox est le goulot : chaque stat, page et plage est une requete HTTPS qu’il relaie au cluster. Les sessions d’un backend partagent un client HTTP.
timeout_secs couvre une plage entiere : sur un lien lent, montez-le plutot que de baisser read_ahead_bytes.
Les petits fichiers coutent chacun un GETFILESTATUS et un OPEN : ce backend sert a parcourir HDFS, pas de stockage courant.
Le corps d’une erreur de Knox n’est jamais recopie dans un journal : seuls le nom de l’exception et le code.