apache / apache/fluss

[docs] Flink add_acl examples in procedures.md do not match the implementation

Open Beginner friendly
#4,099 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
2.1k
Forks
625
Avg merge
3d 14h
Merged PRs (30d)
97

Description

### Search before asking

- [x] I searched in the [issues](https://github.com/apache/fluss/issues) and found nothing similar.

### Fluss version

0.9.0 (latest release)

Tested with `apache/fluss:0.9.1-incubating` / `apache/fluss-quickstart-flink:1.20-0.9.1-incubating`. The same text is still on current `website/docs/engine-flink/procedures.md`.

### Please describe the bug 🐞

The Flink Procedures page documents `sys.add_acl` with values the procedure cannot accept. The Security page (`website/docs/security/authorization.md`) already has the correct format.

Against a SASL + authorizer cluster from the Security quickstart, the documented examples fail as follows.

**1. Table resource without the `cluster.` prefix**

Documented example:

```sql
CALL sys.add_acl(
resource => 'my_database.my_table',
permission => 'ALLOW',
principal => 'User:Bob',
operation => 'WRITE',
host => '192.168.1.100'
);
```

Result:

```
java.lang.IllegalArgumentException: resource must be in format cluster.${database}.${table}
```

`AbstractAclProcedure` requires `cluster`, `cluster.`, or `cluster..`. `'CLUSTER'` happens to work because the first segment is compared case-insensitively, but `'my_database.my_table'` does not.

**2. `DENY` is documented as a valid permission**

The page says valid values are `'ALLOW'` or `'DENY'`. Calling `add_acl` with `permission => 'DENY'` fails:

```
java.lang.IllegalArgumentException: No enum constant org.apache.fluss.security.acl.PermissionType.DENY
```

`PermissionType` only has `ANY` and `ALLOW`, with a comment that DENY will be added later. `authorization.md` already says only `ALLOW` is supported.

**3. Operation names that do not exist**

The page lists `'DELETE'`, `'CLUSTER_ACTION'`, and `'IDEMPOTENT_WRITE'`. `OperationType` is `ANY` / `ALL` / `READ` / `WRITE` / `CREATE` / `DROP` / `ALTER` / `DESCRIBE`. `operation => 'DELETE'` fails with:

```
java.lang.IllegalArgumentException: No enum constant org.apache.fluss.security.acl.OperationType.DELETE
```

`drop_acl` / `list_acl` say they accept the same values as `add_acl`, so those sections inherit the same mistakes.

### Solution

Align `procedures.md` with `authorization.md` and the procedure parser:

- Resource: `cluster`, `cluster.`, `cluster..`
- Permission: `ALLOW` only (until DENY exists)
- Operation: `READ`, `WRITE`, `CREATE`, `DROP`, `ALTER`, `DESCRIBE`, `ALL`

Replace the table-level example with something like `cluster.my_database.my_table`.

### Are you willing to submit a PR?

- [x] I'm willing to submit a PR!

Contributor guide

No contributing guide indexed for this repository

Research direction

Compare website/docs/engine-flink/procedures.md with website/docs/security/authorization.md, then check AbstractAclProcedure, PermissionType, and OperationType to confirm the accepted values. Update the resource, permission, and operation descriptions and the table-level example; done means add_acl, drop_acl, and list_acl document only values supported by the parser.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, sql
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
92/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.